Cookbooks: make examples more clear and remove naming (#1881)

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

1 files changed, 26 insertions, 66 deletions

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index b85ceadc..290a6c82 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -46,6 +46,10 @@ class Foo extends RawModule {
   bundle.foo := 0xc.U
   bundle.bar := 0x3.U
   val uint = bundle.asUInt
+  printf(p"$uint") // 195
+
+  // Test
+  assert(uint === 0xc3.U)
 }
 ```
 
@@ -64,6 +68,12 @@ class MyBundle extends Bundle {
 class Foo extends RawModule {
   val uint = 0xb4.U
   val bundle = uint.asTypeOf(new MyBundle)
+  
+  printf(p"$bundle") // Bundle(foo -> 11, bar -> 4)
+
+  // Test
+  assert(bundle.foo === 0xb.U)
+  assert(bundle.bar === 0x4.U)
 }
 ```
 
@@ -107,6 +117,14 @@ import chisel3._
 class Foo extends RawModule {
   val uint = 0xc.U
   val vec = VecInit(uint.asBools)
+
+  printf(p"$vec") // Vec(0, 0, 1, 1)
+
+  // Test
+  assert(vec(0) === false.B)
+  assert(vec(1) === false.B)
+  assert(vec(2) === true.B)
+  assert(vec(3) === true.B)
 }
 ```
 
@@ -120,6 +138,13 @@ import chisel3._
 class Foo extends RawModule {
   val vec = VecInit(true.B, false.B, true.B, true.B)
   val uint = vec.asUInt
+
+  printf(p"$uint") // 13
+
+  // Test
+  // (remember leftmost Bool in Vec is low order bit)
+  assert(0xd.U === uint)
+
 }
 ```
 
@@ -331,73 +356,8 @@ class ModuleWithOptionalIO(flag: Boolean) extends Module {
 
 ### How do I get Chisel to name signals properly in blocks like when/withClockAndReset?
 
-To get Chisel to name signals (wires and registers) declared inside of blocks like `when`, `withClockAndReset`, etc, use the [`@chiselName`](https://www.chisel-lang.org/api/latest/chisel3/experimental/package$$chiselName.html) annotation as shown below:
-
-```scala mdoc:silent:reset
-import chisel3._
-import chisel3.experimental.chiselName
-
-@chiselName
-class TestMod extends Module {
-  val io = IO(new Bundle {
-    val a = Input(Bool())
-    val b = Output(UInt(4.W))
-  })
-  when (io.a) {
-    val innerReg = RegInit(5.U(4.W))
-    innerReg := innerReg + 1.U
-    io.b := innerReg
-  } .otherwise {
-    io.b := 10.U
-  }
-}
-```
-
-Note that you will need to add the following line to your project's `build.sbt` file.
-
-```scala
-addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full)
-```
-
-If we compile this module *without* `@chiselName`, Chisel is not able to name `innerReg` correctly (notice the `_T`):
-
-```scala mdoc:passthrough
-import chisel3.stage.{ChiselStage, ChiselGeneratorAnnotation}
-import firrtl.annotations.DeletedAnnotation
-import firrtl.EmittedVerilogCircuitAnnotation
-
-class TestModWithout extends Module {
-  override val desiredName = "TestMod"
-  val io = IO(new Bundle {
-    val a = Input(Bool())
-    val b = Output(UInt(4.W))
-  })
-  when (io.a) {
-    val innerReg = RegInit(5.U(4.W))
-    innerReg := innerReg + 1.U
-    io.b := innerReg
-  } .otherwise {
-    io.b := 10.U
-  }
-}
+Use the compiler plugin, and check out the [Naming Cookbook](#naming) if that still does not do what you want.
 
-(new ChiselStage)
-  .execute(Array("-X", "verilog"), Seq(ChiselGeneratorAnnotation(() => new TestModWithout)))
-  .collectFirst{ case DeletedAnnotation(_, a: EmittedVerilogCircuitAnnotation) => a.value.value }
-  .foreach(a => println(s"""|```verilog
-                            |$a
-                            |```""".stripMargin))
-```
-
-However, if we use `@chiselName` then the register previously called `_T` is now `innerReg`:
-```scala mdoc:passthrough
-(new ChiselStage)
-  .execute(Array("-X", "verilog"), Seq(ChiselGeneratorAnnotation(() => new TestMod)))
-  .collectFirst{ case DeletedAnnotation(_, a: EmittedVerilogCircuitAnnotation) => a.value.value }
-  .foreach(a => println(s"""|```verilog
-                            |$a
-                            |```""".stripMargin))
-```
 ### How do I get Chisel to name the results of vector reads properly?
 Currently, name information is lost when using dynamic indexing. For example:
 ```scala mdoc:silent