Promote ChiselEnum user APIs from experimental (backport #2929) (#2931)

* Promote ChiselEnum user APIs from experimental (#2929)

They are commonly used and if we were ever to change them, we will need
to go through a deprecation process anyway.

Note that the EnumAnnotations remain in chisel3.experimental because,
like all Chisel annotation support, they are slated to be deprecated and
removed.

(cherry picked from commit 424e9446f1675fe0168e22bdfbbe85db997376e6)

# Conflicts:
#	docs/src/cookbooks/verilog-vs-chisel.md
#	docs/src/explanations/chisel-enum.md

* Maintain binary compatbility, use aliases in chisel3 package

* Deprecate the actual classes in chisel3.experimental
* Also fix backport conflicts

Co-authored-by: Jack Koenig <koenig@sifive.com>

3 files changed, 2 insertions, 6 deletions

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index e7485e66..5b8239a7 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -445,13 +445,12 @@ getVerilogString(new Top(new UsingCloneTypeBundle(UInt(8.W))))
 
 ### How do I create a finite state machine (FSM)?
 
-The advised way is to use [`ChiselEnum`](https://www.chisel-lang.org/api/latest/chisel3/experimental/index.html#ChiselEnum=chisel3.experimental.EnumFactory) to construct enumerated types representing the state of the FSM.
-State transitions are then handled with [`switch`](https://www.chisel-lang.org/api/latest/chisel3/util/switch$.html)/[`is`](https://www.chisel-lang.org/api/latest/chisel3/util/is$.html) and [`when`](https://www.chisel-lang.org/api/latest/chisel3/when$.html)/[`.elsewhen`](https://www.chisel-lang.org/api/latest/chisel3/WhenContext.html#elsewhen(elseCond:=%3Echisel3.Bool)(block:=%3EUnit)(implicitsourceInfo:chisel3.internal.sourceinfo.SourceInfo,implicitcompileOptions:chisel3.CompileOptions):chisel3.WhenContext)/[`.otherwise`](https://www.chisel-lang.org/api/latest/chisel3/WhenContext.html#otherwise(block:=%3EUnit)(implicitsourceInfo:chisel3.internal.sourceinfo.SourceInfo,implicitcompileOptions:chisel3.CompileOptions):Unit).
+The advised way is to use `ChiselEnum` to construct enumerated types representing the state of the FSM.
+State transitions are then handled with `switch`/`is` and `when`/`.elsewhen`/`.otherwise`.
 
 ```scala mdoc:silent:reset
 import chisel3._
 import chisel3.util.{switch, is}
-import chisel3.experimental.ChiselEnum
 
 object DetectTwoOnes {
   object State extends ChiselEnum {
diff --git a/docs/src/cookbooks/verilog-vs-chisel.md b/docs/src/cookbooks/verilog-vs-chisel.md
index 1adf609e..75cc0ec8 100644
--- a/docs/src/cookbooks/verilog-vs-chisel.md
+++ b/docs/src/cookbooks/verilog-vs-chisel.md
@@ -15,7 +15,6 @@ This page serves as a quick introduction to Chisel for those familiar with Veril
 import chisel3._
 import chisel3.util.{switch, is}
 import chisel3.stage.ChiselStage
-import chisel3.experimental.ChiselEnum
 import chisel3.util.{Cat, Fill, DecoupledIO}
 ```
 
diff --git a/docs/src/explanations/chisel-enum.md b/docs/src/explanations/chisel-enum.md
index 16b5570d..b76fd746 100644
--- a/docs/src/explanations/chisel-enum.md
+++ b/docs/src/explanations/chisel-enum.md
@@ -16,8 +16,6 @@ In contrast with `Chisel.util.Enum`, `ChiselEnum` are subclasses of `Data`, whic
 import chisel3._
 import chisel3.util._
 import chisel3.stage.ChiselStage
-import chisel3.experimental.ChiselEnum
-import chisel3.experimental.suppressEnumCastWarning
 ```
 
 ```scala mdoc:invisible