From 96830a4ad502019ff1040889a89375ff1e3a6c6b Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Tue, 16 Aug 2022 16:57:34 +0000
Subject: Add a cookbook and publicly visible scaladoc for prefix, noPrefix
 (#2687) (#2690)

* Add a cookbook and publicly visible scaladoc for prefix, noPrefix

(cherry picked from commit ae7dc30b3b99f1fbd91c35f54bc19be7c55f74a3)

Co-authored-by: Megan Wachs <megan@sifive.com>---
 .../main/scala/chisel3/experimental/package.scala  | 28 ++++++++-
 docs/src/cookbooks/naming.md                       | 66 +++++++++++++++++++---
 2 files changed, 83 insertions(+), 11 deletions(-)

diff --git a/core/src/main/scala/chisel3/experimental/package.scala b/core/src/main/scala/chisel3/experimental/package.scala
index b1d9cae4..39131943 100644
--- a/core/src/main/scala/chisel3/experimental/package.scala
+++ b/core/src/main/scala/chisel3/experimental/package.scala
@@ -235,9 +235,33 @@ package object experimental {
     }
   }
 
-  // Use to add a prefix to any component generated in input scope
+  /** Use to add a prefix to any components generated in the provided scope.
+    *
+    * @example {{{
+    *
+    * val x1 = prefix("first") {
+    *   // Anything generated here will be prefixed with "first"
+    * }
+    *
+    * val x2 = prefix(mysignal) {
+    *   // Anything generated here will be prefixed with the name of mysignal
+    * }
+    *
+    * }}}
+    */
   val prefix = chisel3.internal.prefix
-  // Use to remove prefixes not in provided scope
+
+  /** Use to clear existing prefixes so no signals within the scope are prefixed
+    * by signals/names outside the scope
+    *
+    * @example {{{
+    *
+    * val x1 = prefix("first") {
+    *   // Anything generated here will have no prefix.
+    *   // The result returned from this would *still* be called `x1` however.
+    * }
+    * }}}
+    */
   val noPrefix = chisel3.internal.noPrefix
 
   // ****************************** Hardware equivalents of Scala Tuples ******************************
diff --git a/docs/src/cookbooks/naming.md b/docs/src/cookbooks/naming.md
index c7ccdd96..ff3cb892 100644
--- a/docs/src/cookbooks/naming.md
+++ b/docs/src/cookbooks/naming.md
@@ -6,20 +6,66 @@ section: "chisel3"
 
 ```scala mdoc:invisible
 import chisel3._
-import chisel3.experimental.prefix
-import chisel3.experimental.noPrefix
 import chisel3.stage.ChiselStage
 ```
 # Naming Cookbook
+
 ### I still have _T signals, can this be fixed?
 
-First check - is the compiler plugin properly enabled? Scalac plugins are enabled via the scalac option
-`-Xplugin:<path/to/jar>`. You can check which compiler plugins are enabled by running `show Compile / scalacOptions` in
-the sbt prompt.
+See the next answer!
+
+### I have so many wires with the same name, like `x`, `x_1` and `x_2`. How can I make them easier to understand?
+
+Signals with `_T` names or names that Chisel has to uniquify
+often are intermediate values generated within loops, function calls, or `when` predicates.
+They can also be consumed by verification statements like `assert` or `prints`.
+In these cases, the compiler plugin often can't find a good prefix for the generated
+intermediate signals and can't name them at all or has to make up a unique name for them.
+
+We recommend you manually insert calls to `prefix` to clarify these cases:
+
+```scala mdoc:silent
+import chisel3.experimental.prefix
+class ExamplePrefix extends Module {
+
+  Seq.tabulate{2} {i =>
+    Seq.tabulate{2}{ j =>
+      prefix(s"loop_${i}_${j}"){
+        val x = WireInit((i*0x10+j).U(8.W))
+        dontTouch(x)
+      }
+    }
+  }
+}
+```
+```scala mdoc:verilog
+ChiselStage.emitVerilog(new ExamplePrefix)
+```
+### How can I get better names for code generated by `when` clauses?
+
+The `prefix` API can help with code inside `when` clauses:
+
+```scala mdoc:silent
+class ExampleWhenPrefix extends Module {
 
-If the plugin is enabled, these signals could be intermediate values which are consumed by either assertions or when
-predicates. In these cases, the compiler plugin often can't find a good prefix for the generated intermediate signals.
-We recommend you manually insert calls to `prefix` to fix these cases. We did this to Rocket Chip and saw huge benefits!
+  val in = IO(Input(UInt(4.W)))
+  val out = IO(Output(UInt(4.W)))
+
+  out := DontCare
+
+  Seq.tabulate{2}{ i =>
+    val j = i + 1
+    when (in === j.U) { prefix(s"clause_${j}"){
+      val foo = Wire(UInt(4.W))
+      foo := in +& j.U(4.W)
+      out := foo
+    }}
+  }
+}
+```
+```scala mdoc:verilog
+ChiselStage.emitVerilog(new ExampleWhenPrefix)
+```
 
 ### I still see _GEN signals, can this be fixed?
 
@@ -43,11 +89,13 @@ name collisions, which are what triggers all those annoying signal name bumps!
 
 Use the `.suggestName` method, which is on all classes which subtype `Data`.
 
-### All this prefixing is annoying, how do I fix it?
+### How can I omit the prefix in certain parts of the code?
 
 You can use the `noPrefix { ... }` to strip the prefix from all signals generated in that scope.
 
 ```scala mdoc
+import chisel3.experimental.noPrefix
+
 class ExampleNoPrefix extends Module {
   val in = IO(Input(UInt(2.W)))
   val out = IO(Output(UInt()))
-- 
cgit v1.2.3