Fix almost all Scaladoc warnings

This fixes all Scaladoc warnings except for those trying to link to
Java.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

19 files changed, 182 insertions, 183 deletions

diff --git a/src/main/scala/firrtl/AddDescriptionNodes.scala b/src/main/scala/firrtl/AddDescriptionNodes.scala
index 1ed3259f..2cd8b9f7 100644
--- a/src/main/scala/firrtl/AddDescriptionNodes.scala
+++ b/src/main/scala/firrtl/AddDescriptionNodes.scala
@@ -60,10 +60,9 @@ private case class DescribedMod(description: Description,
   def foreachInfo(f: Info => Unit): Unit = mod.foreachInfo(f)
 }
 
-/** Wraps modules or statements with their respective described nodes.
-  * Descriptions come from [[DescriptionAnnotation]]. Describing a
-  * module or any of its ports will turn it into a [[DescribedMod]].
-  * Describing a Statement will turn it into a [[DescribedStmt]]
+/** Wraps modules or statements with their respective described nodes. Descriptions come from [[DescriptionAnnotation]].
+  * Describing a module or any of its ports will turn it into a `DescribedMod`. Describing a Statement will turn it into
+  * a (private) `DescribedStmt`.
   *
   * @note should only be used by VerilogEmitter, described nodes will
   *       break other transforms.
diff --git a/src/main/scala/firrtl/Driver.scala b/src/main/scala/firrtl/Driver.scala
index c277e120..e96c3c5b 100644
--- a/src/main/scala/firrtl/Driver.scala
+++ b/src/main/scala/firrtl/Driver.scala
@@ -17,7 +17,6 @@ import firrtl.annotations.AnnotationYamlProtocol._
 import firrtl.passes.{PassException, PassExceptions}
 import firrtl.transforms._
 import firrtl.Utils.throwInternalError
-import firrtl.stage.TargetDirAnnotation
 
 
 /**
diff --git a/src/main/scala/firrtl/Namespace.scala b/src/main/scala/firrtl/Namespace.scala
index 11595ba3..bb358be6 100644
--- a/src/main/scala/firrtl/Namespace.scala
+++ b/src/main/scala/firrtl/Namespace.scala
@@ -3,7 +3,6 @@
 package firrtl
 
 import scala.collection.mutable
-import scala.collection.mutable.HashSet
 import firrtl.ir._
 
 class Namespace private {
@@ -39,8 +38,8 @@ class Namespace private {
 
   def newTemp: String = newName(tempNamePrefix)
 
-  /** Create a copy of the [[scala.collection.mutable.HashSet HashSet]] backing this [[Namespace]]
-    * @return a copy of the underlying [[scala.collection.mutable.HashSet HashSet]]
+  /** Create a copy of the HashSet backing this [[Namespace]]
+    * @return a copy of the underlying HashSet
     */
   def cloneUnderlying: mutable.HashSet[String] = namespace.clone
 }
@@ -83,4 +82,3 @@ object Namespace {
     namespace
   }
 }
-
diff --git a/src/main/scala/firrtl/Parser.scala b/src/main/scala/firrtl/Parser.scala
index 8b0f5b6b..2e3ddde0 100644
--- a/src/main/scala/firrtl/Parser.scala
+++ b/src/main/scala/firrtl/Parser.scala
@@ -20,15 +20,15 @@ case class SyntaxErrorsException(message: String) extends ParserException(messag
 
 object Parser extends LazyLogging {
 
-  /** Parses a file in a given filename and returns a parsed [[Circuit]] */
+  /** Parses a file in a given filename and returns a parsed [[firrtl.ir.Circuit Circuit]] */
   def parseFile(filename: String, infoMode: InfoMode): Circuit =
     parseCharStream(CharStreams.fromFileName(filename), infoMode)
 
-  /** Parses a String and returns a parsed [[Circuit]] */
+  /** Parses a String and returns a parsed [[firrtl.ir.Circuit Circuit]] */
   def parseString(text: String, infoMode: InfoMode): Circuit =
     parseCharStream(CharStreams.fromString(text), infoMode)
 
-  /** Parses a org.antlr.v4.runtime.CharStream and returns a parsed [[Circuit]] */
+  /** Parses a org.antlr.v4.runtime.CharStream and returns a parsed [[firrtl.ir.Circuit Circuit]] */
   def parseCharStream(charStream: CharStream, infoMode: InfoMode): Circuit = {
     val (parseTimeMillis, cst) = time {
       val parser = {
diff --git a/src/main/scala/firrtl/RenameMap.scala b/src/main/scala/firrtl/RenameMap.scala
index c41f15b9..7b0388bc 100644
--- a/src/main/scala/firrtl/RenameMap.scala
+++ b/src/main/scala/firrtl/RenameMap.scala
@@ -37,32 +37,38 @@ object RenameMap {
 // TODO This should probably be refactored into immutable and mutable versions
 final class RenameMap private () {
 
-  /** Record that the from [[CircuitTarget]] is renamed to another [[CircuitTarget]]
+  /** Record that the from [[firrtl.annotations.CircuitTarget CircuitTarget]] is renamed to another
+    * [[firrtl.annotations.CircuitTarget CircuitTarget]]
     * @param from
     * @param to
     */
   def record(from: CircuitTarget, to: CircuitTarget): Unit = completeRename(from, Seq(to))
 
-  /** Record that the from [[CircuitTarget]] is renamed to another sequence of [[CircuitTarget]]s
+  /** Record that the from [[firrtl.annotations.CircuitTarget CircuitTarget]] is renamed to another sequence of
+    * [[firrtl.annotations.CircuitTarget CircuitTarget]]s
     * @param from
     * @param tos
     */
   def record(from: CircuitTarget, tos: Seq[CircuitTarget]): Unit = completeRename(from, tos)
 
-  /** Record that the from [[IsMember]] is renamed to another [[IsMember]]
+  /** Record that the from [[firrtl.annotations.IsMember Member]] is renamed to another [[firrtl.annotations.IsMember
+    * IsMember]]
     * @param from
     * @param to
     */
   def record(from: IsMember, to: IsMember): Unit = completeRename(from, Seq(to))
 
-  /** Record that the from [[IsMember]] is renamed to another sequence of [[IsMember]]s
+  /** Record that the from [[firrtl.annotations.IsMember IsMember]] is renamed to another sequence of
+    * [[firrtl.annotations.IsMember IsMember]]s
     * @param from
     * @param tos
     */
   def record(from: IsMember, tos: Seq[IsMember]): Unit = completeRename(from, tos)
 
-  /** Records that the keys in map are also renamed to their corresponding value seqs.
-    * Only ([[CircuitTarget]] -> Seq[ [[CircuitTarget]] ]) and ([[IsMember]] -> Seq[ [[IsMember]] ]) key/value allowed
+  /** Records that the keys in map are also renamed to their corresponding value seqs. Only
+    * ([[firrtl.annotations.CircuitTarget CircuitTarget]] -> Seq[ [[firrtl.annotations.CircuitTarget CircuitTarget]] ])
+    * and ([[firrtl.annotations.IsMember IsMember]] -> Seq[ [[firrtl.annotations.IsMember IsMember]] ]) key/value
+    * allowed
     * @param map
     */
   def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
@@ -73,30 +79,30 @@ final class RenameMap private () {
       case other => Utils.throwInternalError(s"Illegal rename: ${other._1} -> ${other._2}")
     }
 
-  /** Records that a [[CompleteTarget]] is deleted
+  /** Records that a [[firrtl.annotations.CompleteTarget CompleteTarget]] is deleted
     * @param name
     */
   def delete(name: CompleteTarget): Unit = underlying(name) = Seq.empty
 
-  /** Renames a [[CompleteTarget]]
+  /** Renames a [[firrtl.annotations.CompleteTarget CompleteTarget]]
     * @param t target to rename
     * @return renamed targets
     */
   def apply(t: CompleteTarget): Seq[CompleteTarget] = completeGet(t).getOrElse(Seq(t))
 
-  /** Get renames of a [[CircuitTarget]]
+  /** Get renames of a [[firrtl.annotations.CircuitTarget CircuitTarget]]
     * @param key Target referencing the original circuit
     * @return Optionally return sequence of targets that key remaps to
     */
   def get(key: CompleteTarget): Option[Seq[CompleteTarget]] = completeGet(key)
 
-  /** Get renames of a [[CircuitTarget]]
+  /** Get renames of a [[firrtl.annotations.CircuitTarget CircuitTarget]]
     * @param key Target referencing the original circuit
     * @return Optionally return sequence of targets that key remaps to
     */
   def get(key: CircuitTarget): Option[Seq[CircuitTarget]] = completeGet(key).map( _.map { case x: CircuitTarget => x } )
 
-  /** Get renames of a [[IsMember]]
+  /** Get renames of a [[firrtl.annotations.IsMember IsMember]]
     * @param key Target referencing the original member of the circuit
     * @return Optionally return sequence of targets that key remaps to
     */
@@ -165,7 +171,7 @@ final class RenameMap private () {
     }
   }
 
-  /** Get renames of a [[CompleteTarget]]
+  /** Get renames of a [[firrtl.annotations.CompleteTarget CompleteTarget]]
     * @param key Target referencing the original circuit
     * @return Optionally return sequence of targets that key remaps to
     */
@@ -315,7 +321,7 @@ final class RenameMap private () {
     }
   }
 
-  /* DEPRECATED ACCESSOR/SETTOR METHODS WITH [[Named]] */
+  /* DEPRECATED ACCESSOR/SETTOR METHODS WITH [[firrtl.ir.Named Named]] */
 
   @deprecated("Use record with CircuitTarget instead, this will be removed in 1.3", "1.2")
   def rename(from: Named, to: Named): Unit = rename(from, Seq(to))
@@ -420,5 +426,3 @@ final class RenameMap private () {
   @deprecated("Use typesafe rename defs instead, this will be removed in 1.3", "1.2")
   def delete(names: Seq[String]): Unit = names.foreach(delete(_))
 }
-
-
diff --git a/src/main/scala/firrtl/analyses/InstanceGraph.scala b/src/main/scala/firrtl/analyses/InstanceGraph.scala
index c4a70c73..1c6ada4e 100644
--- a/src/main/scala/firrtl/analyses/InstanceGraph.scala
+++ b/src/main/scala/firrtl/analyses/InstanceGraph.scala
@@ -74,7 +74,7 @@ class InstanceGraph(c: Circuit) {
     instances flatMap { i => fullHierarchy(i) }
   }
 
-  /** An `[[EulerTour]]` representation of the `[[DiGraph]]` */
+  /** An [[firrtl.graph.EulerTour EulerTour]] representation of the [[firrtl.graph.DiGraph DiGraph]] */
   lazy val tour = EulerTour(graph, trueTopInstance)
 
   /** Finds the lowest common ancestor instances for two module names in
diff --git a/src/main/scala/firrtl/annotations/Annotation.scala b/src/main/scala/firrtl/annotations/Annotation.scala
index 62c2b335..25e361f3 100644
--- a/src/main/scala/firrtl/annotations/Annotation.scala
+++ b/src/main/scala/firrtl/annotations/Annotation.scala
@@ -34,7 +34,7 @@ trait Annotation extends Product {
     }.foldRight(Seq.empty[Target])((seq, c) => c ++ seq)
   }
 
-  /** Returns all [[Target]] members in this annotation
+  /** Returns all [[firrtl.annotations.Target Target]] members in this annotation
     * @return
     */
   def getTargets: Seq[Target] = extractComponents(productIterator.toSeq)
@@ -210,4 +210,3 @@ private[firrtl] object LegacyAnnotation {
 case class DeletedAnnotation(xFormName: String, anno: Annotation) extends NoTargetAnnotation {
   override def serialize: String = s"""DELETED by $xFormName\n${anno.serialize}"""
 }
-
diff --git a/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala b/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala
index 7c7ef096..c5dae954 100644
--- a/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala
+++ b/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala
@@ -4,8 +4,7 @@ package firrtl.annotations
 
 import java.io.File
 
-/**
-  * Enumeration of the two types of readmem statements available in verilog
+/** Enumeration of the two types of `readmem` statements available in Verilog.
   */
 object MemoryLoadFileType extends Enumeration {
   type FileType = Value
@@ -14,11 +13,10 @@ object MemoryLoadFileType extends Enumeration {
   val Binary: Value = Value("b")
 }
 
-/**
-  * Firrtl implementation for load memory
+/** Firrtl implementation for load memory
   * @param target        memory to load
   * @param fileName      name of input file
-  * @param hexOrBinary   use $readmemh or $readmemb
+  * @param hexOrBinary   use `\$readmemh` or `\$readmemb`
   */
 case class LoadMemoryAnnotation(
   target: ComponentName,
diff --git a/src/main/scala/firrtl/options/phases/ConvertLegacyAnnotations.scala b/src/main/scala/firrtl/options/phases/ConvertLegacyAnnotations.scala
index 37667160..7ff05370 100644
--- a/src/main/scala/firrtl/options/phases/ConvertLegacyAnnotations.scala
+++ b/src/main/scala/firrtl/options/phases/ConvertLegacyAnnotations.scala
@@ -6,7 +6,7 @@ import firrtl.AnnotationSeq
 import firrtl.annotations.LegacyAnnotation
 import firrtl.options.Phase
 
-/** Convert any [[LegacyAnnotation]]s to non-legacy variants */
+/** Convert any [[firrtl.annotations.LegacyAnnotation LegacyAnnotation]]s to non-legacy variants */
 object ConvertLegacyAnnotations extends Phase {
 
   def transform(annotations: AnnotationSeq): AnnotationSeq = LegacyAnnotation.convertLegacyAnnos(annotations)
diff --git a/src/main/scala/firrtl/passes/ExpandWhens.scala b/src/main/scala/firrtl/passes/ExpandWhens.scala
index 9136c913..560a1c1c 100644
--- a/src/main/scala/firrtl/passes/ExpandWhens.scala
+++ b/src/main/scala/firrtl/passes/ExpandWhens.scala
@@ -14,16 +14,16 @@ import collection.mutable
 import collection.immutable.ListSet
 
 /** Expand Whens
-*
-* This pass does the following things:
-* $ - Remove last connect semantics
-* $ - Remove conditional blocks
-* $ - Eliminate concept of scoping
-* $ - Consolidate attaches
-*
-* @note Assumes bulk connects and isInvalids have been expanded
-* @note Assumes all references are declared
-*/
+  *
+  * This pass does the following things:
+  * $ - Remove last connect semantics
+  * $ - Remove conditional blocks
+  * $ - Eliminate concept of scoping
+  * $ - Consolidate attaches
+  *
+  * @note Assumes bulk connects and isInvalids have been expanded
+  * @note Assumes all references are declared
+  */
 object ExpandWhens extends Pass {
   /** Returns circuit with when and last connection semantics resolved */
   def run(c: Circuit): Circuit = {
@@ -79,23 +79,22 @@ object ExpandWhens extends Pass {
 
     val infoMap: InfoMap = new InfoMap
 
-    /**
-      * Adds into into map, aggregates info into MultiInfo where necessary
-      * @param key  serialized name of node
-      * @param info info being recorded
-      */
+    /* Adds into into map, aggregates info into MultiInfo where necessary
+     * @param key  serialized name of node
+     * @param info info being recorded
+     */
     def saveInfo(key: String, info: Info): Unit = {
       infoMap(key) = infoMap(key) ++ info
     }
 
-    /** Removes connections/attaches from the statement
-      * Mutates namespace, simlist, nodes, attaches
-      * Mutates input netlist
-      * @param netlist maps references to their values for a given immediate scope
-      * @param defaults sequence of netlists of surrouding scopes, ordered closest to farthest
-      * @param p predicate so far, used to update simulation constructs
-      * @param s statement to expand
-      */
+    /* Removes connections/attaches from the statement
+     * Mutates namespace, simlist, nodes, attaches
+     * Mutates input netlist
+     * @param netlist maps references to their values for a given immediate scope
+     * @param defaults sequence of netlists of surrouding scopes, ordered closest to farthest
+     * @param p predicate so far, used to update simulation constructs
+     * @param s statement to expand
+     */
     def expandWhens(netlist: Netlist,
                     defaults: Defaults,
                     p: Expression)
@@ -137,13 +136,13 @@ object ExpandWhens extends Pass {
         EmptyStmt
       // Expand conditionally, see comments below
       case sx: Conditionally =>
-        /** 1) Recurse into conseq and alt with empty netlist, updated defaults, updated predicate
-          * 2) For each assigned reference (lvalue) in either conseq or alt, get merged value
-          *   a) Find default value from defaults
-          *   b) Create Mux, ValidIf or WInvalid, depending which (or both) conseq/alt assigned lvalue
-          * 3) If a merged value has been memoized, update netlist. Otherwise, memoize then update netlist.
-          * 4) Return conseq and alt declarations, followed by memoized nodes
-          */
+        /* 1) Recurse into conseq and alt with empty netlist, updated defaults, updated predicate
+         * 2) For each assigned reference (lvalue) in either conseq or alt, get merged value
+         *   a) Find default value from defaults
+         *   b) Create Mux, ValidIf or WInvalid, depending which (or both) conseq/alt assigned lvalue
+         * 3) If a merged value has been memoized, update netlist. Otherwise, memoize then update netlist.
+         * 4) Return conseq and alt declarations, followed by memoized nodes
+         */
         val conseqNetlist = new Netlist
         val altNetlist = new Netlist
         val conseqStmt = expandWhens(conseqNetlist, netlist +: defaults, AND(p, sx.pred))(sx.conseq)
@@ -269,4 +268,3 @@ object ExpandWhens extends Pass {
   private def NOT(e: Expression) =
     DoPrim(Eq, Seq(e, zero), Nil, BoolType)
 }
-
diff --git a/src/main/scala/firrtl/passes/RemoveValidIf.scala b/src/main/scala/firrtl/passes/RemoveValidIf.scala
index 5338a911..b9f13139 100644
--- a/src/main/scala/firrtl/passes/RemoveValidIf.scala
+++ b/src/main/scala/firrtl/passes/RemoveValidIf.scala
@@ -7,7 +7,7 @@ import firrtl.ir._
 import Utils.throwInternalError
 import WrappedExpression.weq
 
-/** Remove ValidIf and replace IsInvalid with a connection to zero */
+/** Remove [[firrtl.ir.ValidIf ValidIf]] and replace [[firrtl.ir.IsInvalid IsInvalid]] with a connection to zero */
 object RemoveValidIf extends Pass {
 
   val UIntZero = Utils.zero
@@ -15,8 +15,8 @@ object RemoveValidIf extends Pass {
   val ClockZero = DoPrim(PrimOps.AsClock, Seq(UIntZero), Seq.empty, ClockType)
   val FixedZero = FixedLiteral(BigInt(0), IntWidth(1), IntWidth(0))
 
-  /** Returns an [[Expression]] equal to zero for a given [[GroundType]]
-    * @note Accepts [[Type]] but dyanmically expects [[GroundType]]
+  /** Returns an [[firrtl.ir.Expression Expression]] equal to zero for a given [[firrtl.ir.GroundType GroundType]]
+    * @note Accepts [[firrtl.ir.Type Type]] but dyanmically expects [[firrtl.ir.GroundType GroundType]]
     */
   def getGroundZero(tpe: Type): Expression = tpe match {
     case _: UIntType => UIntZero
diff --git a/src/main/scala/firrtl/stage/FirrtlAnnotations.scala b/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
index e13daf79..c88591fb 100644
--- a/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
+++ b/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
@@ -115,7 +115,7 @@ case object LogClassNamesAnnotation extends NoTargetAnnotation with FirrtlOption
 
 /** Additional arguments
   *  - set with any trailing option on the command line
-  * @param value one [[scala.String]] argument
+  * @param value one [[scala.Predef.String String]] argument
   */
 case class ProgramArgsAnnotation(value: String) extends NoTargetAnnotation with FirrtlOption {
   def addOptions(p: OptionParser[AnnotationSeq]): Unit = p.arg[String]("<arg>...")
@@ -193,9 +193,9 @@ case class InfoModeAnnotation(value: String = "append") extends NoTargetAnnotati
     .text(s"specifies the source info handling, default is ${FirrtlExecutionOptions().infoModeName}")
 }
 
-/** Holds a [[scala.String]] containing FIRRTL source to read as input
+/** Holds a [[scala.Predef.String String]] containing FIRRTL source to read as input
   *  - set with `--firrtl-source`
-  * @param value FIRRTL source as a [[scala.String]]
+  * @param value FIRRTL source as a [[scala.Predef.String String]]
   */
 case class FirrtlSourceAnnotation(value: String) extends NoTargetAnnotation with FirrtlOption {
   def addOptions(p: OptionParser[AnnotationSeq]): Unit = p.opt[String]("firrtl-source")
@@ -282,7 +282,7 @@ object RunFirrtlTransformAnnotation {
   private [firrtl] def apply(): RunFirrtlTransformAnnotation = RunFirrtlTransformAnnotation(new firrtl.transforms.VerilogRename)
 }
 
-/** Holds a FIRRTL [[Circuit]]
+/** Holds a FIRRTL [[firrtl.ir.Circuit Circuit]]
   * @param value a circuit
   */
 case class FirrtlCircuitAnnotation(value: Circuit) extends NoTargetAnnotation with FirrtlOption {
diff --git a/src/main/scala/firrtl/transforms/CheckCombLoops.scala b/src/main/scala/firrtl/transforms/CheckCombLoops.scala
index 9016dca4..0a9ec0e3 100644
--- a/src/main/scala/firrtl/transforms/CheckCombLoops.scala
+++ b/src/main/scala/firrtl/transforms/CheckCombLoops.scala
@@ -53,10 +53,10 @@ case class CombinationalPath(sink: ComponentName, sources: Seq[ComponentName]) e
   }
 }
 
-/** Finds and detects combinational logic loops in a circuit, if any
-  * exist. Returns the input circuit with no modifications.
+/** Finds and detects combinational logic loops in a circuit, if any exist. Returns the input circuit with no
+  * modifications.
   *
-  * @throws CombLoopException if a loop is found
+  * @throws firrtl.transforms.CheckCombLoops.CombLoopException if a loop is found
   * @note Input form: Low FIRRTL
   * @note Output form: Low FIRRTL (identity transform)
   * @note The pass looks for loops through combinational-read memories
diff --git a/src/main/scala/firrtl/transforms/CombineCats.scala b/src/main/scala/firrtl/transforms/CombineCats.scala
index 1265a5c3..ac8fc5fb 100644
--- a/src/main/scala/firrtl/transforms/CombineCats.scala
+++ b/src/main/scala/firrtl/transforms/CombineCats.scala
@@ -13,7 +13,7 @@ import scala.collection.mutable
 case class MaxCatLenAnnotation(maxCatLen: Int) extends NoTargetAnnotation
 
 object CombineCats {
-  /** Mapping from references to the [[Expression]]s that drive them paired with their Cat length */
+  /** Mapping from references to the [[firrtl.ir.Expression Expression]]s that drive them paired with their Cat length */
   type Netlist = mutable.HashMap[WrappedExpression, (Int, Expression)]
 
   def expandCatArgs(maxCatLen: Int, netlist: Netlist)(expr: Expression): (Int, Expression) = expr match {
@@ -65,4 +65,3 @@ class CombineCats extends Transform {
     state.copy(circuit = state.circuit.copy(modules = modulesx))
   }
 }
-
diff --git a/src/main/scala/firrtl/transforms/ConstantPropagation.scala b/src/main/scala/firrtl/transforms/ConstantPropagation.scala
index fdaa7112..66d82c04 100644
--- a/src/main/scala/firrtl/transforms/ConstantPropagation.scala
+++ b/src/main/scala/firrtl/transforms/ConstantPropagation.scala
@@ -313,24 +313,24 @@ class ConstantPropagation extends Transform with ResolvedAnnotationPaths {
     else constPropExpression(nodeMap, instMap, constSubOutputs)(propagated)
   }
 
-  /** Constant propagate a Module
-    *
-    * Two pass process
-    * 1. Propagate constants in expressions and forward propagate references
-    * 2. Propagate references again for backwards reference (Wires)
-    * TODO Replacing all wires with nodes makes the second pass unnecessary
-    *   However, preserving decent names DOES require a second pass
-    *   Replacing all wires with nodes makes it unnecessary for preserving decent names to trigger an
-    *   extra iteration though
-    *
-    * @param m the Module to run constant propagation on
-    * @param dontTouches names of components local to m that should not be propagated across
-    * @param instMap map of instance names to Module name
-    * @param constInputs map of names of m's input ports to literal driving it (if applicable)
-    * @param constSubOutputs Map of Module name to Map of output port name to literal driving it
-    * @return (Constpropped Module, Map of output port names to literal value,
-    *   Map of submodule modulenames to Map of input port names to literal values)
-    */
+  /* Constant propagate a Module
+   *
+   * Two pass process
+   * 1. Propagate constants in expressions and forward propagate references
+   * 2. Propagate references again for backwards reference (Wires)
+   * TODO Replacing all wires with nodes makes the second pass unnecessary
+   *   However, preserving decent names DOES require a second pass
+   *   Replacing all wires with nodes makes it unnecessary for preserving decent names to trigger an
+   *   extra iteration though
+   *
+   * @param m the Module to run constant propagation on
+   * @param dontTouches names of components local to m that should not be propagated across
+   * @param instMap map of instance names to Module name
+   * @param constInputs map of names of m's input ports to literal driving it (if applicable)
+   * @param constSubOutputs Map of Module name to Map of output port name to literal driving it
+   * @return (Constpropped Module, Map of output port names to literal value,
+   *   Map of submodule modulenames to Map of input port names to literal values)
+   */
   @tailrec
   private def constPropModule(
       m: Module,
@@ -419,14 +419,15 @@ class ConstantPropagation extends Transform with ResolvedAnnotationPaths {
         // Const prop registers that are driven by a mux tree containing only instances of one constant or self-assigns
         // This requires that reset has been made explicit
         case Connect(_, lref @ WRef(lname, ltpe, RegKind, _), rhs) if !dontTouches(lname) && !asyncResetRegs(lname) =>
-          /** Checks if an RHS expression e of a register assignment is convertible to a constant assignment.
-            * Here, this means that e must be 1) a literal, 2) a self-connect, or 3) a mux tree of cases (1) and (2).
-            * In case (3), it also recursively checks that the two mux cases are convertible to constants and
-            * uses pattern matching on the returned options to check that they are convertible to the *same* constant.
-            * When encountering a node reference, it expands the node by to its RHS assignment and recurses.
-            *
-            * @return an option containing the literal or self-connect that e is convertible to, if any
-            */
+
+          /* Checks if an RHS expression e of a register assignment is convertible to a constant assignment.
+           * Here, this means that e must be 1) a literal, 2) a self-connect, or 3) a mux tree of cases (1) and (2).
+           * In case (3), it also recursively checks that the two mux cases are convertible to constants and
+           * uses pattern matching on the returned options to check that they are convertible to the *same* constant.
+           * When encountering a node reference, it expands the node by to its RHS assignment and recurses.
+           *
+           * @return an option containing the literal or self-connect that e is convertible to, if any
+           */
           def regConstant(e: Expression): Option[Expression] = e match {
             case lit: Literal => Some(pad(lit, ltpe))
             case WRef(regName, _, RegKind, _) if (regName == lname) => Some(e)
diff --git a/src/main/scala/firrtl/transforms/FlattenRegUpdate.scala b/src/main/scala/firrtl/transforms/FlattenRegUpdate.scala
index 2bce124c..2d04dc89 100644
--- a/src/main/scala/firrtl/transforms/FlattenRegUpdate.scala
+++ b/src/main/scala/firrtl/transforms/FlattenRegUpdate.scala
@@ -11,14 +11,14 @@ import scala.collection.mutable
 
 object FlattenRegUpdate {
 
-  /** Mapping from references to the [[Expression]]s that drive them */
+  /** Mapping from references to the [[firrtl.ir.Expression Expression]]s that drive them */
   type Netlist = mutable.HashMap[WrappedExpression, Expression]
 
   /** Build a [[Netlist]] from a Module's connections and Nodes
     *
-    * This assumes [[LowForm]]
+    * This assumes [[firrtl.LowForm LowForm]]
     *
-    * @param mod [[Module]] from which to build a [[Netlist]]
+    * @param mod [[firrtl.ir.Module Module]] from which to build a [[Netlist]]
     * @return [[Netlist]] of the module's connections and nodes
     */
   def buildNetlist(mod: Module): Netlist = {
@@ -43,8 +43,8 @@ object FlattenRegUpdate {
     * Constructs nested mux trees (up to a certain arbitrary threshold) for register updates. This
     * can result in dead code that this function does NOT remove.
     *
-    * @param mod [[Module]] to transform
-    * @return [[Module]] with register updates flattened
+    * @param mod [[firrtl.ir.Module Module]] to transform
+    * @return [[firrtl.ir.Module Module]] with register updates flattened
     */
   def flattenReg(mod: Module): Module = {
     // We want to flatten Mux trees for reg updates into if-trees for
diff --git a/src/main/scala/firrtl/transforms/ReplaceTruncatingArithmetic.scala b/src/main/scala/firrtl/transforms/ReplaceTruncatingArithmetic.scala
index 9c809c5f..1fe9a723 100644
--- a/src/main/scala/firrtl/transforms/ReplaceTruncatingArithmetic.scala
+++ b/src/main/scala/firrtl/transforms/ReplaceTruncatingArithmetic.scala
@@ -10,15 +10,15 @@ import scala.collection.mutable
 
 object ReplaceTruncatingArithmetic {
 
-  /** Mapping from references to the [[Expression]]s that drive them */
+  /** Mapping from references to the [[firrtl.ir.Expression Expression]]s that drive them */
   type Netlist = mutable.HashMap[WrappedExpression, Expression]
 
   private val SeqBIOne = Seq(BigInt(1))
 
   /** Replaces truncating arithmetic in an Expression
     *
-    * @param netlist a '''mutable''' HashMap mapping references to [[DefNode]]s to their connected
-    * [[Expression]]s. It is '''not''' mutated in this function
+    * @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
     * @param expr the Expression being transformed
     * @return Returns expr with truncating arithmetic replaced
     */
@@ -35,8 +35,9 @@ object ReplaceTruncatingArithmetic {
 
   /** Replaces truncating arithmetic in a Statement
     *
-    * @param netlist a '''mutable''' HashMap mapping references to [[DefNode]]s to their connected
-    * [[Expression]]s. This function '''will''' mutate it if stmt contains a [[DefNode]]
+    * @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 contains a [[firrtl.ir.DefNode
+    * DefNode]]
     * @param stmt the Statement being searched for nodes and transformed
     * @return Returns stmt with truncating arithmetic replaced
     */
@@ -70,4 +71,3 @@ class ReplaceTruncatingArithmetic extends Transform {
     state.copy(circuit = state.circuit.copy(modules = modulesx))
   }
 }
-
diff --git a/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala b/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala
index 6df6733d..f3f10e72 100644
--- a/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala
+++ b/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala
@@ -14,11 +14,10 @@ import scala.collection.mutable
 
 /** Ledger tracks [[firrtl.ir.Circuit]] statistics
   *
-  * In this lesson, we want to count the number of muxes in each
-  *  module in our design.
+  * In this lesson, we want to count the number of muxes in each module in our design.
   *
-  * This [[Ledger]] class will be passed along as we walk our
-  *  circuit, and help us count each [[Mux]] we find.
+  * This [[Ledger]] class will be passed along as we walk our circuit, and help us count each [[firrtl.ir.Mux Mux]] we
+  * find.
   *
   * See [[lesson1.AnalyzeCircuit]]
   */
@@ -47,18 +46,18 @@ class Ledger {
 
 /** AnalyzeCircuit Transform
   *
-  * Walks [[firrtl.ir.Circuit]], and records the number of muxes it finds, per module.
+  * Walks [[firrtl.ir.Circuit Circuit]], and records the number of muxes it finds, per module.
   *
-  * While some compiler frameworks operate on graphs, we represent a Firrtl
-  * circuit using a tree representation:
-  *   - A Firrtl [[Circuit]] contains a sequence of [[DefModule]]s.
-  *   - A [[DefModule]] contains a sequence of [[Port]]s, and maybe a [[Statement]].
-  *   - A [[Statement]] can contain other [[Statement]]s, or [[Expression]]s.
-  *   - A [[Expression]] can contain other [[Expression]]s.
-  * 
-  * To visit all Firrtl IR nodes in a circuit, we write functions that recursively
-  *  walk down this tree. To record statistics, we will pass along the [[Ledger]]
-  *  class and use it when we come across a [[Mux]].
+  * While some compiler frameworks operate on graphs, we represent a Firrtl circuit using a tree representation:
+  *   - A Firrtl [[firrtl.ir.Circuit Circuit]] contains a sequence of [[firrtl.ir.DefModule DefModule]]s.
+  *   - A [[firrtl.ir.DefModule DefModule]] contains a sequence of [[firrtl.ir.Port Port]]s, and maybe a
+  *     [[firrtl.ir.Statement Statement]].
+  *   - A [[firrtl.ir.Statement Statement]] can contain other [[firrtl.ir.Statement Statement]]s, or
+  *     [[firrtl.ir.Expression Expression]]s.
+  *   - A [[firrtl.ir.Expression Expression]] can contain other [[firrtl.ir.Expression Expression]]s.
+  *
+  * To visit all Firrtl IR nodes in a circuit, we write functions that recursively walk down this tree. To record
+  * statistics, we will pass along the [[Ledger]] class and use it when we come across a [[firrtl.ir.Mux Mux]].
   *
   * See the following links for more detailed explanations:
   * Firrtl's IR:
@@ -69,73 +68,81 @@ class Ledger {
   *   - https://github.com/ucb-bar/firrtl/wiki/Common-Pass-Idioms
   */
 class AnalyzeCircuit extends Transform {
-  // Requires the [[Circuit]] form to be "low"
+  /** Requires the [[firrtl.ir.Circuit Circuit]] form to be "low" */
   def inputForm = LowForm
-  // Indicates the output [[Circuit]] form to be "low"
+  /** Indicates the output [[firrtl.ir.Circuit Circuit]] form to be "low" */
   def outputForm = LowForm
 
-  // Called by [[Compiler]] to run your pass. [[CircuitState]] contains
-  // the circuit and its form, as well as other related data.
+  /** Called by [[firrtl.Compiler Compiler]] to run your pass. [[firrtl.CircuitState CircuitState]] contains the circuit
+    * and its form, as well as other related data.
+    */
   def execute(state: CircuitState): CircuitState = {
     val ledger = new Ledger()
     val circuit = state.circuit
 
-    // Execute the function walkModule(ledger) on every [[DefModule]] in
-    // circuit, returning a new [[Circuit]] with new [[Seq]] of [[DefModule]].
-    //   - "higher order functions" - using a function as an object
-    //   - "function currying" - partial argument notation
-    //   - "infix notation" - fancy function calling syntax
-    //   - "map" - classic functional programming concept
-    //   - discard the returned new [[Circuit]] because circuit is unmodified
+    /* Execute the function walkModule(ledger) on every [[firrtl.ir.DefModule DefModule]] in circuit, returning a new
+     * [[Circuit]] with new [[scala.collection.Seq Seq]] of [[firrtl.ir.DefModule DefModule]].
+     *   - "higher order functions" - using a function as an object
+     *   - "function currying" - partial argument notation
+     *   - "infix notation" - fancy function calling syntax
+     *   - "map" - classic functional programming concept
+     *   - discard the returned new [[firrtl.ir.Circuit Circuit]] because circuit is unmodified
+     */
     circuit map walkModule(ledger)
 
     // Print our ledger
     println(ledger.serialize)
 
-    // Return an unchanged [[CircuitState]]
+    // Return an unchanged [[firrtl.CircuitState CircuitState]]
     state
   }
 
-  // Deeply visits every [[Statement]] in m.
+  /** Deeply visits every [[firrtl.ir.Statement Statement]] in m. */
   def walkModule(ledger: Ledger)(m: DefModule): DefModule = {
     // Set ledger to current module name
     ledger.setModuleName(m.name)
 
-    // Execute the function walkStatement(ledger) on every [[Statement]] in m.
-    //   - return the new [[DefModule]] (in this case, its identical to m)
-    //   - if m does not contain [[Statement]], map returns m.
+    /* Execute the function walkStatement(ledger) on every [[firrtl.ir.Statement Statement]] in m.
+     *   - return the new [[firrtl.ir.DefModule DefModule]] (in this case, its identical to m)
+     *   - if m does not contain [[firrtl.ir.Statement Statement]], map returns m.
+     */
     m map walkStatement(ledger)
   }
 
-  // Deeply visits every [[Statement]] and [[Expression]] in s.
+  /** Deeply visits every [[firrtl.ir.Statement Statement]] and [[firrtl.ir.Expression Expression]] in s. */
   def walkStatement(ledger: Ledger)(s: Statement): Statement = {
 
-    // Execute the function walkExpression(ledger) on every [[Expression]] in s.
-    //   - discard the new [[Statement]] (in this case, its identical to s)
-    //   - if s does not contain [[Expression]], map returns s.
+    /* Execute the function walkExpression(ledger) on every [[firrtl.ir.Expression Expression]] in s.
+     *   - discard the new [[firrtl.ir.Statement Statement]] (in this case, its identical to s)
+     *   - if s does not contain [[firrtl.ir.Expression Expression]], map returns s.
+     */
     s map walkExpression(ledger)
 
-    // Execute the function walkStatement(ledger) on every [[Statement]] in s.
-    //   - return the new [[Statement]] (in this case, its identical to s)
-    //   - if s does not contain [[Statement]], map returns s.
+    /* Execute the function walkStatement(ledger) on every [[firrtl.ir.Statement Statement]] in s.
+     *   - return the new [[firrtl.ir.Statement Statement]] (in this case, its identical to s)
+     *   - if s does not contain [[firrtl.ir.Statement Statement]], map returns s.
+     */
     s map walkStatement(ledger)
   }
 
-  // Deeply visits every [[Expression]] in e.
-  //   - "post-order traversal" - handle e's children [[Expression]] before e
+  /** Deeply visits every [[firrtl.ir.Expression Expression]] in e.
+    *   - "post-order traversal"
+    *   - handle e's children [[firrtl.ir.Expression Expression]] before e
+    */
   def walkExpression(ledger: Ledger)(e: Expression): Expression = {
 
-    // Execute the function walkExpression(ledger) on every [[Expression]] in e.
-    //   - return the new [[Expression]] (in this case, its identical to e)
-    //   - if s does not contain [[Expression]], map returns e.
+    /** Execute the function walkExpression(ledger) on every [[firrtl.ir.Expression Expression]] in e.
+      *   - return the new [[firrtl.ir.Expression Expression]] (in this case, its identical to e)
+      *   - if s does not contain [[firrtl.ir.Expression Expression]], map returns e.
+      */
     val visited = e map walkExpression(ledger)
 
     visited match {
-      // If e is a [[Mux]], increment our ledger and return e.
+      // If e is a [[firrtl.ir.Mux Mux]], increment our ledger and return e.
       case Mux(cond, tval, fval, tpe) =>
         ledger.foundMux
         e
-      // If e is not a [[Mux]], return e.
+      // If e is not a [[firrtl.ir.Mux Mux]], return e.
       case notmux => notmux
     }
   }
diff --git a/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala b/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala
index 87b87004..1905aeb5 100644
--- a/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala
+++ b/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala
@@ -15,12 +15,11 @@ import firrtl.Mappers._
 import scala.collection.mutable
 
 /** Ledger tracks [[firrtl.ir.Circuit]] statistics
-  * 
-  * In this lesson, we want to calculate the number of muxes, not just in 
-  *  a module, but also in any instances it has of other modules, etc.
   *
-  * To do this, we need to update our Ledger class to keep track of this
-  *  module instance information
+  * In this lesson, we want to calculate the number of muxes, not just in a module, but also in any instances it has of
+  * other modules, etc.
+  *
+  * To do this, we need to update our Ledger class to keep track of this module instance information
   *
   * See [[lesson2.AnalyzeCircuit]]
   */
@@ -63,39 +62,37 @@ class Ledger {
 
 /** AnalyzeCircuit Transform
   *
-  * Walks [[firrtl.ir.Circuit]], and records the number of muxes and instances it
-  *  finds, per module.
+  * Walks [[firrtl.ir.Circuit]], and records the number of muxes and instances it finds, per module.
   *
-  * While the Firrtl parser emits a bare form of the IR (located in firrtl.ir._),
-  *  it is often useful to have more information in these case classes. To do this,
-  *  the Firrtl compiler has mirror "working" classes for the following IR
-  *  nodes (which contain additional fields):
+  * While the Firrtl parser emits a bare form of the IR (located in firrtl.ir._), it is often useful to have more
+  * information in these case classes. To do this, the Firrtl compiler has mirror "working" classes for the following IR
+  * nodes (which contain additional fields):
   *   - DefInstance -> WDefInstance
   *   - SubAccess -> WSubAccess
   *   - SubIndex -> WSubIndex
   *   - SubField -> WSubField
   *   - Reference -> WRef
   *
-  * Take a look at [[ToWorkingIR]] in src/main/scala/firrtl/passes/Passes.scala
-  *  to see how Firrtl IR nodes are replaced with working IR nodes.
+  * Take a look at [[firrtl.passes.ToWorkingIR ToWorkginIR]] in
+  * [[https://github.com/freechipsproject/firrtl/tree/master/src/main/scala/firrtl/passes
+  * src/main/scala/firrtl/passes/Passes.scala]] to see how Firrtl IR nodes are replaced with working IR nodes.
   *
-  * Future lessons will explain the WIR's additional fields. For now, it is
-  *  enough to know that the transform [[ResolveAndCheck]] populates these
-  *  fields, and checks the legality of the circuit. If your transform is
-  *  creating new WIR nodes, use the following "unknown" values in the WIR
-  *  node, and then call [[ResolveAndCheck]] at the end of your transform:
+  * Future lessons will explain the WIR's additional fields. For now, it is enough to know that the transform
+  * [[firrtl.ResolveAndCheck]] populates these fields, and checks the legality of the circuit. If your transform is
+  * creating new WIR nodes, use the following "unknown" values in the WIR node, and then call [[firrtl.ResolveAndCheck]]
+  * at the end of your transform:
   *   - Kind -> ExpKind
   *   - Gender -> UNKNOWNGENDER
   *   - Type -> UnknownType
   *
-  * The following [[CircuitForm]]s require WIR instead of IR nodes:
+  * The following [[firrtl.CircuitForm]]s require WIR instead of IR nodes:
   *   - HighForm
   *   - MidForm
   *   - LowForm
   *
   * See the following links for more detailed explanations:
   * IR vs Working IR
-  *   - TODO(izraelevitz) 
+  *   - TODO(izraelevitz)
   */
 class AnalyzeCircuit extends Transform {
   def inputForm = LowForm
@@ -128,11 +125,11 @@ class AnalyzeCircuit extends Transform {
   // Deeply visits every [[Statement]] and [[Expression]] in s.
   def walkStatement(ledger: Ledger)(s: Statement): Statement = {
     // Map the functions walkStatement(ledger) and walkExpression(ledger)
-    val visited = s map walkStatement(ledger) map walkExpression(ledger) 
+    val visited = s map walkStatement(ledger) map walkExpression(ledger)
     visited match {
       // IR node [[DefInstance]] is previously replaced by WDefInstance, a
       //  "working" IR node
-      case DefInstance(info, name, module) => 
+      case DefInstance(info, name, module) =>
         Utils.error("All DefInstances should have been replaced by WDefInstances")
       // Working IR Node [[WDefInstance]] is what the compiler uses
       // See src/main/scala/firrtl/WIR.scala for all working IR nodes