Refine autonaming to have more intuitive behavior (#1660)

* Refine autonaming to have more intuitive behavior

Last name in an Expression wins, while the first Statement to name wins.
This is done via checking the _id of HasIds during autonaming and only
applying a name if the HasId was created in the scope of autonaming.
There is no change to .autoSeed or .suggestName behavior.

Behavior of chisel3-plugins from before this change is maintained.

* Update docs with naming plugin changes

2 files changed, 25 insertions, 10 deletions

diff --git a/docs/src/cookbooks/naming.md b/docs/src/cookbooks/naming.md
index 150f0639..4caabaff 100644
--- a/docs/src/cookbooks/naming.md
+++ b/docs/src/cookbooks/naming.md
@@ -42,7 +42,7 @@ name collisions, which are what triggers all those annoying signal name bumps!
 
 ### I want to force a signal (or instance) name to something, how do I do that?
 
-Use the `.suggestName` method, which is on all classes which subtype 'Data'.
+Use the `.suggestName` method, which is on all classes which subtype `Data`.
 
 ### All this prefixing is annoying, how do I fix it?
 
diff --git a/docs/src/explanations/naming.md b/docs/src/explanations/naming.md
index 86db515c..a626b878 100644
--- a/docs/src/explanations/naming.md
+++ b/docs/src/explanations/naming.md
@@ -42,11 +42,11 @@ side with a call to `autoNameRecursively`, which names the signal/module.
 ```scala mdoc
 class MyBundle extends Bundle {
   val foo = Input(UInt(3.W))
-  // val foo = autoNameRecursively("foo", Input(UInt(3.W)))
+  // val foo = autoNameRecursively("foo")(Input(UInt(3.W)))
 }
 class Example1 extends MultiIOModule {
   val io = IO(new MyBundle())
-  // val io = autoNameRecursively("io", IO(new MyBundle()))
+  // val io = autoNameRecursively("io")(IO(new MyBundle()))
 }
 println(ChiselStage.emitVerilog(new Example1))
 ```
@@ -57,15 +57,15 @@ side of the val declaration:
 ```scala mdoc
 class Example2 extends MultiIOModule {
   val in = IO(Input(UInt(2.W)))
-  // val in = autoNameRecursively("in", prefix("in")(IO(Input(UInt(2.W)))))
+  // val in = autoNameRecursively("in")(prefix("in")(IO(Input(UInt(2.W)))))
 
   val out = IO(Output(UInt(2.W)))
-  // val out = autoNameRecursively("out", prefix("out")(IO(Output(UInt(2.W)))))
+  // val out = autoNameRecursively("out")(prefix("out")(IO(Output(UInt(2.W)))))
 
   def inXin() = in * in
 
   val add = 3.U + inXin()
-  // val add = autoNameRecursively("add", prefix("add")(3.U + inXin()))
+  // val add = autoNameRecursively("add")(prefix("add")(3.U + inXin()))
   // Note that the intermediate result of the multiplication is prefixed with `add`
 
   out := add + 1.U
@@ -79,16 +79,16 @@ Note that the naming also works if the hardware type is nested in an `Option` or
 ```scala mdoc
 class Example3 extends MultiIOModule {
   val in = IO(Input(UInt(2.W)))
-  // val in = autoNameRecursively("in", prefix("in")(IO(Input(UInt(2.W)))))
+  // val in = autoNameRecursively("in")(prefix("in")(IO(Input(UInt(2.W)))))
 
   val out = IO(Output(UInt()))
-  // val out = autoNameRecursively("out", prefix("out")(IO(Output(UInt(2.W)))))
+  // val out = autoNameRecursively("out")(prefix("out")(IO(Output(UInt(2.W)))))
 
   def inXin() = in * in
 
   val opt = Some(3.U + inXin())
   // Note that the intermediate result of the inXin() is prefixed with `opt`:
-  // val opt = autoNameRecursively("opt", prefix("opt")(Some(3.U + inXin())))
+  // val opt = autoNameRecursively("opt")(prefix("opt")(Some(3.U + inXin())))
 
   out := opt.get + 1.U
 }
@@ -96,6 +96,21 @@ class Example3 extends MultiIOModule {
 println(ChiselStage.emitVerilog(new Example3))
 ```
 
+There is also a slight variant (`autoNameRecursivelyProduct`) for naming hardware with names provided by an unapply:
+```scala mdoc
+class UnapplyExample extends MultiIOModule {
+  def mkIO() = (IO(Input(UInt(2.W))), IO(Output(UInt())))
+  val (in, out) = mkIO()
+  // val (in, out) = autoNameRecursivelyProduct(List(Some("in"), Some("out")))(mkIO())
+
+  out := in
+}
+
+println(ChiselStage.emitVerilog(new UnapplyExample))
+```
+Note that the compiler plugin will not insert a prefix in these cases because it is ambiguous what the prefix should be.
+Users who desire a prefix are encouraged to provide one as [described below](#prefixing).
+
 ### Prefixing
 
 As shown above, the compiler plugin automatically attempts to prefix some of your signals for you. However, you as a
@@ -226,4 +241,4 @@ class Example10 extends MultiIOModule {
 ### @chiselName
 
 This macro is no longer recommended as its functionality is entirely replaced by the compiler plugin. Feel free to
-delete from your Chisel designs!
\ No newline at end of file
+delete from your Chisel designs!