Eliminate warnings on `sbt doc` and `sbt unidoc` (#1470)

* Eliminate warnings on `sbt doc` and `sbt unidoc`
- removed toFirrtl reference on MultiTargetAnnotation
- lots of places where package path has to be added to comment references
- Change to use `/** text starts here` convention when wrong in comment with a doc fix.
  - Did not exhaustively change these
- Wrestled doc example in RenderDiGraph#renderNode, not sure if I won
- Cleaned up InferWidths & CatchExceptions imports
- Added missing license message to a couple of files.
- fixed a couple of stale parameter names in scaladoc
- Added @unchecked to stop erasure warning in Emitting where emission annotations are collected
- Change types to [_] on match in RenameMap#recordAll to fix erasure warning

* Where  possible change [[firrtl.ir.X]] to [[firrtl.ir.X X]] for better display in scaladoc

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

4 files changed, 25 insertions, 28 deletions

diff --git a/src/main/scala/firrtl/transforms/InferResets.scala b/src/main/scala/firrtl/transforms/InferResets.scala
index 72724b27..4342f276 100644
--- a/src/main/scala/firrtl/transforms/InferResets.scala
+++ b/src/main/scala/firrtl/transforms/InferResets.scala
@@ -96,7 +96,7 @@ object InferResets {
   }
 }
 
-/** Infers the concrete type of [[ResetType]]s by their connections
+/** Infers the concrete type of [[firrtl.ir.ResetType ResetType]]s by their connections
   *
   * There are 3 cases
   * 1. An abstract reset driven by and/or driving only asynchronous resets will be inferred as
@@ -105,7 +105,7 @@ object InferResets {
   *    error
   * 1. Otherwise, the reset is inferred as synchronous (i.e. the abstract reset is only invalidated
   *    or is driven by or drives only synchronous resets)
-  * @note This is a global inference because ports can be of type [[ResetType]]
+  * @note This is a global inference because ports can be of type [[firrtl.ir.ResetType ResetType]]
   * @note This transform should be run before [[DedupModules]] so that similar Modules from
   *   generator languages like Chisel can infer differently
   */
diff --git a/src/main/scala/firrtl/transforms/InlineBitExtractions.scala b/src/main/scala/firrtl/transforms/InlineBitExtractions.scala
index 617dff96..9ed5aafa 100644
--- a/src/main/scala/firrtl/transforms/InlineBitExtractions.scala
+++ b/src/main/scala/firrtl/transforms/InlineBitExtractions.scala
@@ -1,3 +1,5 @@
+// See LICENSE for license details.
+
 package firrtl
 package transforms
 
@@ -38,10 +40,10 @@ object InlineBitExtractionsTransform {
   /** Mapping from references to the [[firrtl.ir.Expression Expression]]s that drive them */
   type Netlist = mutable.HashMap[WrappedExpression, Expression]
 
-  /** Recursively replace [[WRef]]s with new [[Expression]]s
+  /** Recursively replace [[WRef]]s with new [[firrtl.ir.Expression Expression]]s
     *
     * @param netlist a '''mutable''' HashMap mapping references to [[firrtl.ir.DefNode DefNode]]s to their connected
-    * [[firrtl.ir.Expression Expression]]s. It is '''not''' mutated in this function
+    * [[firrtl.ir.Expression Expression Expression]]s. It is '''not''' mutated in this function
     * @param expr the Expression being transformed
     * @return Returns expr with Bits inlined
     */
@@ -74,8 +76,8 @@ object InlineBitExtractionsTransform {
   /** Inline bits in a Statement
     *
     * @param netlist a '''mutable''' HashMap mapping references to [[firrtl.ir.DefNode DefNode]]s to their connected
-    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate it if stmt is a [[firrtl.ir.DefNode
-    * DefNode]] with a Temporary name and a value that is a [[PrimOp]] Bits
+    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate it if stmt is
+    * a [[firrtl.ir.DefNode DefNode]] with a Temporary name and a value that is a [[firrtl.ir.PrimOp PrimOp]] Bits
     * @param stmt the Statement being searched for nodes and transformed
     * @return Returns stmt with Bits inlined
     */
diff --git a/src/main/scala/firrtl/transforms/InlineCasts.scala b/src/main/scala/firrtl/transforms/InlineCasts.scala
index eeafb0e4..2ebee225 100644
--- a/src/main/scala/firrtl/transforms/InlineCasts.scala
+++ b/src/main/scala/firrtl/transforms/InlineCasts.scala
@@ -1,3 +1,5 @@
+// See LICENSE for license details.
+
 package firrtl
 package transforms
 
@@ -18,7 +20,7 @@ object InlineCastsTransform {
     case _ => false
   }
 
-  /** Recursively replace [[WRef]]s with new [[Expression]]s
+  /** Recursively replace [[WRef]]s with new [[firrtl.ir.Expression Expression]]s
     *
     * @param replace a '''mutable''' HashMap mapping [[WRef]]s to values with which the [[WRef]]
     * will be replaced. It is '''not''' mutated in this function
@@ -42,8 +44,9 @@ object InlineCastsTransform {
   /** Inline casts in a Statement
     *
     * @param netlist a '''mutable''' HashMap mapping references to [[firrtl.ir.DefNode DefNode]]s to their connected
-    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate it if stmt is a [[firrtl.ir.DefNode
-    * DefNode]] with a value that is a cast [[PrimOp]]
+    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate
+    * it if stmt is a [[firrtl.ir.DefNode DefNode]]
+    * with a value that is a cast [[firrtl.ir.PrimOp PrimpOp]]
     * @param stmt the Statement being searched for nodes and transformed
     * @return Returns stmt with casts inlined
     */
diff --git a/src/main/scala/firrtl/transforms/PropagatePresetAnnotations.scala b/src/main/scala/firrtl/transforms/PropagatePresetAnnotations.scala
index 92022278..f36ee5e0 100644
--- a/src/main/scala/firrtl/transforms/PropagatePresetAnnotations.scala
+++ b/src/main/scala/firrtl/transforms/PropagatePresetAnnotations.scala
@@ -3,13 +3,9 @@
 package firrtl
 package transforms
 
-import firrtl.{Utils}
-
-
 import firrtl.PrimOps._
-import firrtl.ir._
-import firrtl.ir.{AsyncResetType}
 import firrtl.annotations._
+import firrtl.ir.{AsyncResetType, _}
 import firrtl.options.{Dependency, PreservesAll}
 
 import scala.collection.mutable
@@ -72,8 +68,8 @@ class PropagatePresetAnnotations extends Transform with PreservesAll[Transform]
     *     - Annotate all leaf register with PresetRegAnnotation
     *     - Annotate all intermediate wire, node, connect with PresetConnectorAnnotation
     *
-    * @param circuit the circuit
-    * @param annotations all the annotations
+    * @param cs the circuit state
+    * @param presetAnnos all the annotations
     * @return updated annotations
     */
   private def propagate(cs: CircuitState, presetAnnos: Seq[PresetAnnotation]): AnnotationSeq = {
@@ -93,8 +89,7 @@ class PropagatePresetAnnotations extends Transform with PreservesAll[Transform]
     * WALK I PHASE 1 FUNCTIONS
     */
 
-    /**
-      * Walk current module
+    /* Walk current module
       *  - process ports
       *     - store connections & entry points for PHASE 2
       *  - process statements
@@ -109,14 +104,13 @@ class PropagatePresetAnnotations extends Transform with PreservesAll[Transform]
       val moduleTarget = circuitTarget.module(m.name)
       val localInstances = new TargetMap()
 
-      /**
-        * Recursively process a given type
+      /* Recursively process a given type
         * Recursive on Bundle and Vector Type only
         * Store Register and Connections for AsyncResetType
-        *
-        * @param tpe Type to be processed
-        * @param target ReferenceTarget associated to the tpe
-        * @param all Boolean indicating whether all subelements of the current tpe should also be stored as Annotated AsyncReset entry points
+        * @param tpe [[Type]] to be processed
+        * @param target [[ReferenceTarget]] associated to the tpe
+        * @param all Boolean indicating whether all subelements of the current
+        *            tpe should also be stored as Annotated AsyncReset entry points
         */
       def processType(tpe: Type, target: ReferenceTarget, all: Boolean): Unit = {
         if(tpe == AsyncResetType){
@@ -149,13 +143,11 @@ class PropagatePresetAnnotations extends Transform with PreservesAll[Transform]
         processType(w.tpe, target, presets.contains(target))
       }
 
-      /**
-        * Recursively search for the ReferenceTarget of a given Expression
-        *
+      /*  Recursively search for the ReferenceTarget of a given Expression
         * @param e Targeted Expression
         * @param ta Local ReferenceTarget of the Targeted Expression
         * @return a ReferenceTarget in case of success, a GenericTarget otherwise
-        * @throw Internal Error on unexpected recursive path return results
+        * @throws [[InternalError]] on unexpected recursive path return results
         */
       def getRef(e: Expression, ta: ReferenceTarget, annoCo: Boolean = false) : Target = {
         e match {