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>

15 files changed, 59 insertions, 65 deletions

diff --git a/src/main/scala/firrtl/Emitter.scala b/src/main/scala/firrtl/Emitter.scala
index 5ab385be..6ab9427e 100644
--- a/src/main/scala/firrtl/Emitter.scala
+++ b/src/main/scala/firrtl/Emitter.scala
@@ -465,8 +465,7 @@ class VerilogEmitter extends SeqTransform with Emitter {
     } 
   }
   
-  /** 
-    * Provide API to retrieve EmissionOptions based on the provided AnnotationSeq 
+  /** Provide API to retrieve EmissionOptions based on the provided [[AnnotationSeq]]
     * 
     * @param annotations : AnnotationSeq to be searched for EmissionOptions
     *
@@ -494,7 +493,9 @@ class VerilogEmitter extends SeqTransform with Emitter {
     def getConnectEmissionOption(target: ReferenceTarget): ConnectEmissionOption =
       connectEmissionOption(target)
 
-    private val emissionAnnos = annotations.collect{ case m : SingleTargetAnnotation[ReferenceTarget] with EmissionOption => m }
+    private val emissionAnnos = annotations.collect{
+      case m : SingleTargetAnnotation[ReferenceTarget] @unchecked with EmissionOption => m
+    }
     // using multiple foreach instead of a single partial function as an Annotation can gather multiple EmissionOptions for simplicity
     emissionAnnos.foreach { case a :RegisterEmissionOption => registerEmissionOption += ((a.target,a)) case _ => }
     emissionAnnos.foreach { case a :WireEmissionOption     => wireEmissionOption += ((a.target,a))     case _ => }
diff --git a/src/main/scala/firrtl/RenameMap.scala b/src/main/scala/firrtl/RenameMap.scala
index 61f1d8f9..543fc1ad 100644
--- a/src/main/scala/firrtl/RenameMap.scala
+++ b/src/main/scala/firrtl/RenameMap.scala
@@ -97,9 +97,9 @@ final class RenameMap private (val underlying: mutable.HashMap[CompleteTarget, S
     */
   def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
     map.foreach{
-      case (from: IsComponent, tos: Seq[IsMember]) => completeRename(from, tos)
-      case (from: IsModule, tos: Seq[IsMember]) => completeRename(from, tos)
-      case (from: CircuitTarget, tos: Seq[CircuitTarget]) => completeRename(from, tos)
+      case (from: IsComponent, tos: Seq[_]) => completeRename(from, tos)
+      case (from: IsModule, tos: Seq[_]) => completeRename(from, tos)
+      case (from: CircuitTarget, tos: Seq[_]) => completeRename(from, tos)
       case other => Utils.throwInternalError(s"Illegal rename: ${other._1} -> ${other._2}")
     }
 
diff --git a/src/main/scala/firrtl/annotations/Annotation.scala b/src/main/scala/firrtl/annotations/Annotation.scala
index 3cf6d5ef..4c39bfee 100644
--- a/src/main/scala/firrtl/annotations/Annotation.scala
+++ b/src/main/scala/firrtl/annotations/Annotation.scala
@@ -80,7 +80,7 @@ trait SingleTargetAnnotation[T <: Named] extends Annotation {
 /** [[MultiTargetAnnotation]] keeps the renamed targets grouped within a single annotation. */
 trait MultiTargetAnnotation extends Annotation {
   /** Contains a sequence of [[Target]].
-    * When creating in [[toFirrtl]], [[targets]] should be assigned by `Seq(Seq(TargetA), Seq(TargetB), Seq(TargetC))`
+    * When created, [[targets]] should be assigned by `Seq(Seq(TargetA), Seq(TargetB), Seq(TargetC))`
     * */
   val targets: Seq[Seq[Target]]
 
diff --git a/src/main/scala/firrtl/constraint/ConstraintSolver.scala b/src/main/scala/firrtl/constraint/ConstraintSolver.scala
index 40fff728..a421ae17 100644
--- a/src/main/scala/firrtl/constraint/ConstraintSolver.scala
+++ b/src/main/scala/firrtl/constraint/ConstraintSolver.scala
@@ -10,7 +10,7 @@ import scala.collection.mutable
 
 /** Forwards-Backwards Constraint Solver
   *
-  * Used for computing [[Width]] and [[Bound]] constraints
+  * Used for computing [[firrtl.ir.Width Width]] and [[firrtl.ir.Bound Bound]] constraints
   *
   * Note - this is an O(N) algorithm, but requires exponential memory. We rely on aggressive early optimization
   *   of constraint expressions to (usually) get around this.
diff --git a/src/main/scala/firrtl/graph/DiGraph.scala b/src/main/scala/firrtl/graph/DiGraph.scala
index e3b5fbe9..f30beec1 100644
--- a/src/main/scala/firrtl/graph/DiGraph.scala
+++ b/src/main/scala/firrtl/graph/DiGraph.scala
@@ -336,7 +336,7 @@ class DiGraph[T] private[graph] (private[graph] val edges: LinkedHashMap[T, Link
     * Any edge including a deleted node will be deleted
     *
     * @param vprime the Set[T] of desired vertices
-    * @throws IllegalArgumentException if vprime is not a subset of V
+    * @throws scala.IllegalArgumentException if vprime is not a subset of V
     * @return the subgraph
     */
   def subgraph(vprime: Set[T]): DiGraph[T] = {
@@ -350,7 +350,7 @@ class DiGraph[T] private[graph] (private[graph] val edges: LinkedHashMap[T, Link
     * transformed into an edge (u,v).
     *
     * @param vprime the Set[T] of desired vertices
-    * @throws IllegalArgumentException if vprime is not a subset of V
+    * @throws scala.IllegalArgumentException if vprime is not a subset of V
     * @return the simplified graph
     */
   def simplify(vprime: Set[T]): DiGraph[T] = {
@@ -394,7 +394,7 @@ class MutableDiGraph[T] extends DiGraph[T](new LinkedHashMap[T, LinkedHashSet[T]
   }
 
   /** Add edge (u,v) to the graph.
-    * @throws IllegalArgumentException if u and/or v is not in the graph
+    * @throws scala.IllegalArgumentException if u and/or v is not in the graph
     */
   def addEdge(u: T, v: T): Unit = {
     require(contains(u))
diff --git a/src/main/scala/firrtl/graph/EdgeData.scala b/src/main/scala/firrtl/graph/EdgeData.scala
index 4c1109ed..16990de0 100644
--- a/src/main/scala/firrtl/graph/EdgeData.scala
+++ b/src/main/scala/firrtl/graph/EdgeData.scala
@@ -34,7 +34,7 @@ trait EdgeData[V, E] {
     * @param u the source of the edge
     * @param v the destination of the edge
     * @throws EdgeNotFoundException if the edge does not exist
-    * @throws NoSuchElementException if the edge has no data
+    * @throws scala.NoSuchElementException if the edge has no data
     */
   def edgeData(u: V, v: V): E = {
     assertEdgeExists(u, v)
@@ -76,25 +76,23 @@ trait MutableEdgeData[V, E] extends EdgeData[V, E] {
     edgeDataMap((u, v)) = data
   }
 
-  /**
-    * Add an edge (u,v) to the graph with associated edge data.
+  /** Add an edge (u,v) to the graph with associated edge data.
     *
-    * @see [[DiGraph.addEdge]]
+    * @see [[MutableDiGraph.addEdge]]
     * @param u the source of the edge
     * @param v the destination of the edge
     * @param data the edge data to associate with the edge
-    * @throws IllegalArgumentException if u or v is not part of the graph
+    * @throws scala.IllegalArgumentException if u or v is not part of the graph
     */
   def addEdge(u: V, v: V, data: E): Unit = {
     addEdge(u, v)
     setEdgeData(u, v, data)
   }
 
-  /**
-    * Safely add an edge (u,v) to the graph with associated edge data. If on or more of the two
+  /** Safely add an edge (u,v) to the graph with associated edge data. If on or more of the two
     * vertices is not present in the graph, add them before creating the edge.
     *
-    * @see [[DiGraph.addPairWithEdge]]
+    * @see [[MutableDiGraph.addPairWithEdge]]
     * @param u the source of the edge
     * @param v the destination of the edge
     * @param data the edge data to associate with the edge
@@ -109,7 +107,7 @@ trait MutableEdgeData[V, E] extends EdgeData[V, E] {
     * are present in the graph. This is useful for preventing spurious edge creating when examining
     * a subset of possible nodes.
     *
-    * @see [[DiGraph.addEdgeIfValid]]
+    * @see [[MutableDiGraph.addEdgeIfValid]]
     * @return a Boolean indicating whether the edge was added
     * @param u the source of the edge
     * @param v the destination of the edge
diff --git a/src/main/scala/firrtl/graph/RenderDiGraph.scala b/src/main/scala/firrtl/graph/RenderDiGraph.scala
index 812a86ef..b3c1373c 100644
--- a/src/main/scala/firrtl/graph/RenderDiGraph.scala
+++ b/src/main/scala/firrtl/graph/RenderDiGraph.scala
@@ -19,10 +19,9 @@ class RenderDiGraph[T <: Any](diGraph: DiGraph[T], graphName: String = "", rankD
 
   /**
     * override this to change the default way a node is displayed. Default is toString surrounded by double quotes
+    * This example changes the double quotes to brackets
     * {{{
-    * val rend = new RenderDiGraph(graph, "alice") {
-    *   override def renderNode(node: Symbol): String = s"\"${symbol.name}\""
-    *   }
+    *   override def renderNode(node: String): String = { "[" + node + "]" }
     * }}}
     */
   def renderNode(node: T): String = {
diff --git a/src/main/scala/firrtl/passes/InferWidths.scala b/src/main/scala/firrtl/passes/InferWidths.scala
index 29936ca0..1e9657cf 100644
--- a/src/main/scala/firrtl/passes/InferWidths.scala
+++ b/src/main/scala/firrtl/passes/InferWidths.scala
@@ -3,16 +3,14 @@
 package firrtl.passes
 
 // Datastructures
-import firrtl._
-import firrtl.annotations.{Annotation, ReferenceTarget}
-import firrtl.ir._
-import firrtl.Utils._
-import firrtl.Mappers._
 import firrtl.Implicits.width2constraint
-import firrtl.annotations.{CircuitTarget, ModuleTarget, ReferenceTarget, Target}
+import firrtl.Mappers._
+import firrtl.Utils._
+import firrtl._
+import firrtl.annotations._
 import firrtl.constraint.{ConstraintSolver, IsMax}
+import firrtl.ir._
 import firrtl.options.{Dependency, PreservesAll}
-import firrtl.traversals.Foreachers._
 
 object InferWidths {
   def apply(): InferWidths = new InferWidths()
diff --git a/src/main/scala/firrtl/passes/RemoveIntervals.scala b/src/main/scala/firrtl/passes/RemoveIntervals.scala
index cf3d2ff2..001c92b3 100644
--- a/src/main/scala/firrtl/passes/RemoveIntervals.scala
+++ b/src/main/scala/firrtl/passes/RemoveIntervals.scala
@@ -26,9 +26,9 @@ class WrapWithRemainder(info: Info, mname: String, wrap: DoPrim)
   * 1) Align binary points
   *    - adds shift operators to primop args and connections
   *    - does not affect declaration- or inferred-types
-  * 2) Replace Interval [[DefNode]] with [[DefWire]] + [[Connect]]
+  * 2) Replace Interval [[firrtl.ir.DefNode DefNode]] with [[firrtl.ir.DefWire DefWire]] + [[firrtl.ir.Connect Connect]]
   *    - You have to do this to capture the smaller bitwidths of nodes that intervals give you. Otherwise, any future
-  *    InferTypes would reinfer the larger widths on these nodes from SInt width inference rules
+  *    InferTypes would re-infer the larger widths on these nodes from SInt width inference rules
   * 3) Replace declaration IntervalType's with SIntType's
   *    - for each declaration:
   *      a. remove non-zero binary points
diff --git a/src/main/scala/firrtl/stage/phases/CatchExceptions.scala b/src/main/scala/firrtl/stage/phases/CatchExceptions.scala
index a7f84b73..f1c588b3 100644
--- a/src/main/scala/firrtl/stage/phases/CatchExceptions.scala
+++ b/src/main/scala/firrtl/stage/phases/CatchExceptions.scala
@@ -2,10 +2,11 @@
 
 package firrtl.stage.phases
 
-import firrtl.{AnnotationSeq, CustomTransformException, FIRRTLException, FirrtlInternalException, FirrtlUserException,
-  Utils}
-import firrtl.options.{DependencyManagerException, Phase, PhaseException, OptionsException}
-import firrtl.passes.{PassException, PassExceptions}
+import firrtl.options.{DependencyManagerException, OptionsException, Phase, PhaseException}
+import firrtl.{
+  AnnotationSeq, CustomTransformException, FIRRTLException,
+  FirrtlInternalException, FirrtlUserException, Utils
+}
 
 import scala.util.control.ControlThrowable
 
diff --git a/src/main/scala/firrtl/stage/transforms/Compiler.scala b/src/main/scala/firrtl/stage/transforms/Compiler.scala
index ded50ce6..b031344f 100644
--- a/src/main/scala/firrtl/stage/transforms/Compiler.scala
+++ b/src/main/scala/firrtl/stage/transforms/Compiler.scala
@@ -2,9 +2,9 @@
 
 package firrtl.stage.transforms
 
-import firrtl.{CircuitState, Transform, VerilogEmitter}
 import firrtl.options.DependencyManagerUtils.CharSet
 import firrtl.stage.TransformManager
+import firrtl.{Transform, VerilogEmitter}
 
 class Compiler(
   targets: Seq[TransformManager.TransformDependency],
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 {