Merge pull request #1022 from freechipsproject/cleanup-scaladoc

Miscellaneous Scaladoc Cleanup

11 files changed, 131 insertions, 129 deletions

diff --git a/build.sbt b/build.sbt
index 0d050f9d..2cffb8b7 100644
--- a/build.sbt
+++ b/build.sbt
@@ -177,7 +177,18 @@ lazy val chisel = (project in file(".")).
       "-diagrams-max-classes", "25",
       "-doc-version", version.value,
       "-doc-title", name.value,
-      "-doc-root-content", baseDirectory.value+"/root-doc.txt"
+      "-doc-root-content", baseDirectory.value+"/root-doc.txt",
+      "-sourcepath", (baseDirectory in ThisBuild).value.toString,
+      "-doc-source-url",
+      {
+        val branch =
+          if (version.value.endsWith("-SNAPSHOT")) {
+            "master"
+          } else {
+            s"v${version.value}"
+          }
+        s"https://github.com/freechipsproject/chisel3/tree/$branch/€{FILE_PATH}.scala"
+      }
     ),
     // Include macro classes, resources, and sources main JAR since we don't create subproject JARs.
     mappings in (Compile, packageBin) ++= (mappings in (coreMacros, Compile, packageBin)).value,
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Annotation.scala b/chiselFrontend/src/main/scala/chisel3/core/Annotation.scala
index b2c9ea78..b7e82f63 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Annotation.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Annotation.scala
@@ -5,7 +5,6 @@ package chisel3.core
 import scala.language.existentials
 
 import chisel3.internal.{Builder, InstanceId}
-import chisel3.core.ImplicitModule
 import firrtl.Transform
 import firrtl.annotations.{Annotation, CircuitName, ComponentName, ModuleName}
 import firrtl.transforms.{DontTouchAnnotation, NoDedupAnnotation}
@@ -30,9 +29,10 @@ object ChiselAnnotation {
     }
 }
 
-/** Mixin for [[ChiselAnnotation]] that instantiates an associated FIRRTL Transform when this
-  * Annotation is present during a run of [[chisel3.Driver.execute]]. Automatic Transform
-  * instantiation is *not* supported when the Circuit and Annotations are serialized before invoking
+/** Mixin for [[ChiselAnnotation]] that instantiates an associated FIRRTL Transform when this Annotation is present
+  * during a run of
+  * [[Driver$.execute(args:Array[String],dut:()=>chisel3\.experimental\.RawModule)* Driver.execute]].
+  * Automatic Transform instantiation is *not* supported when the Circuit and Annotations are serialized before invoking
   * FIRRTL.
   */
 // TODO There should be a FIRRTL API for this instead
@@ -99,7 +99,7 @@ object dontTouch { // scalastyle:ignore object.name
   *        val b = Input(UInt(32.W))
   *        val out = Output(UInt(32.W))
   *      })
-  *      override def desiredName = s"adder_$myNname"
+  *      override def desiredName = "adder_" + myNname
   *      io.out := io.a + io.b
   *    })
   *    doNotDedup(m)
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 424db5cb..b18b27e5 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -1285,7 +1285,7 @@ sealed class Bool() extends UInt(1.W) with Reset {
     *
     * @param that a hardware $coll
     * @return the lgocial or of this $coll and `that`
-    * @note this is equivalent to [[Bool.|]]
+    * @note this is equivalent to [[Bool!.|(that:chisel3\.core\.Bool)* Bool.|)]]
     * @group Logical
     */
   def || (that: Bool): Bool = macro SourceInfoTransform.thatArg
@@ -1297,7 +1297,7 @@ sealed class Bool() extends UInt(1.W) with Reset {
     *
     * @param that a hardware $coll
     * @return the lgocial and of this $coll and `that`
-    * @note this is equivalent to [[Bool.&]]
+    * @note this is equivalent to [[Bool!.&(that:chisel3\.core\.Bool)* Bool.&]]
     * @group Logical
     */
   def && (that: Bool): Bool = macro SourceInfoTransform.thatArg
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 7ff58b54..3ce79786 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -498,7 +498,7 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc { // sc
     case Some(BundleLitBinding(litMap)) => None  // this API does not support Bundle literals
     case _ => None
   }
- 
+
   def isLit(): Boolean = litArg.isDefined
 
   /**
@@ -567,9 +567,8 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc { // sc
 }
 
 trait WireFactory {
-  /** @usecase def apply[T <: Data](t: T): T
-    *   Construct a [[Wire]] from a type template
-    *   @param t The template from which to construct this wire
+  /** Construct a [[Wire]] from a type template
+    * @param t The template from which to construct this wire
     */
   def apply[T <: Data](t: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     if (compileOptions.declaredTypeMustBeUnbound) {
@@ -681,29 +680,25 @@ object WireDefault {
     x
   }
 
-  /** @usecase def apply[T <: Data](t: T, init: DontCare.type): T
-    *   Construct a [[Wire]] with a type template and a [[DontCare]] default
-    *   @param t The type template used to construct this [[Wire]]
-    *   @param init The default connection to this [[Wire]], can only be [[DontCare]]
-    *   @note This is really just a specialized form of `apply[T <: Data](t: T, init: T): T` with [[DontCare]]
-    *   as `init`
+  /** Construct a [[Wire]] with a type template and a [[chisel3.DontCare]] default
+    * @param t The type template used to construct this [[Wire]]
+    * @param init The default connection to this [[Wire]], can only be [[DontCare]]
+    * @note This is really just a specialized form of `apply[T <: Data](t: T, init: T): T` with [[DontCare]] as `init`
     */
   def apply[T <: Data](t: T, init: DontCare.type)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = { // scalastyle:ignore line.size.limit
     applyImpl(t, init)
   }
 
-  /** @usecase def apply[T <: Data](t: T, init: T): T
-    *   Construct a [[Wire]] with a type template and a default connection
-    *   @param t The type template used to construct this [[Wire]]
-    *   @param init The hardware value that will serve as the default value
+  /** Construct a [[Wire]] with a type template and a default connection
+    * @param t The type template used to construct this [[Wire]]
+    * @param init The hardware value that will serve as the default value
     */
   def apply[T <: Data](t: T, init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     applyImpl(t, init)
   }
 
-  /** @usecase def apply[T <: Data](init: T): T
-    *   Construct a [[Wire]] with a default connection
-    *   @param init The hardware value that will serve as a type template and default value
+  /** Construct a [[Wire]] with a default connection
+    * @param init The hardware value that will serve as a type template and default value
     */
   def apply[T <: Data](init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     val model = (init match {
@@ -745,4 +740,3 @@ private[chisel3] object DontCare extends Element {
   // DontCare's only match themselves.
   private[core] def typeEquivalent(that: chisel3.core.Data): Boolean = that == DontCare
 }
-
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Reg.scala b/chiselFrontend/src/main/scala/chisel3/core/Reg.scala
index 27156f8b..747fad73 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Reg.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Reg.scala
@@ -30,10 +30,9 @@ import chisel3.internal.sourceinfo.{SourceInfo}
   *
   */
 object Reg {
-  /** @usecase def apply[T <: Data](t: T): T
-    *   Construct a [[Reg]] from a type template with no initialization value (reset is ignored).
-    *   Value will not change unless the [[Reg]] is given a connection.
-    *   @param t The template from which to construct this wire
+  /** Construct a [[Reg]] from a type template with no initialization value (reset is ignored).
+    * Value will not change unless the [[Reg]] is given a connection.
+    * @param t The template from which to construct this wire
     */
   def apply[T <: Data](t: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     if (compileOptions.declaredTypeMustBeUnbound) {
@@ -143,10 +142,9 @@ object RegNext {
   * }}}
   */
 object RegInit {
-  /** @usecase def apply[T <: Data](t: T, init: T): T
-    *   Construct a [[Reg]] from a type template initialized to the specified value on reset
-    *   @param t The type template used to construct this [[Reg]]
-    *   @param init The value the [[Reg]] is initialized to on reset
+  /** Construct a [[Reg]] from a type template initialized to the specified value on reset
+    * @param t The type template used to construct this [[Reg]]
+    * @param init The value the [[Reg]] is initialized to on reset
     */
   def apply[T <: Data](t: T, init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     if (compileOptions.declaredTypeMustBeUnbound) {
@@ -162,9 +160,8 @@ object RegInit {
     reg
   }
 
-  /** @usecase def apply[T <: Data](init: T): T
-    *   Construct a [[Reg]] initialized on reset to the specified value.
-    *   @param init Initial value that serves as a type template and reset value
+  /** Construct a [[Reg]] initialized on reset to the specified value.
+    * @param init Initial value that serves as a type template and reset value
     */
   def apply[T <: Data](init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     val model = (init match {
diff --git a/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala
index 4e7533d4..4b6b0a8c 100644
--- a/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala
+++ b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala
@@ -15,27 +15,23 @@ package chisel3
   *   <br>
   *
   *   The equivalent public-facing methods do not have the `do_` prefix or have the same name. Use and look at the
-  *   documentation for those. If you want left shift, use `<<`, not `do_<<`. If you want comversion to a [[Seq]] of
-  *   [[Bool]]s look at the `asBools` above, not the one below. Users can safely ignore every method in this group!
-  *   <br>
-  *   <br>
+  *   documentation for those. If you want left shift, use `<<`, not `do_<<`. If you want conversion to a
+  *   [[scala.collection.Seq Seq]] of [[Bool]]s look at the `asBools` above, not the one below. Users can safely ignore
+  *   every method in this group! <br> <br>
   *
   *   🐉🐉🐉 '''Here be dragons...''' 🐉🐉🐉
   *   <br>
   *   <br>
   *
-  *   These `do_X` methods are used to enable both implicit passing of [[SourceInfo]] and
-  *   [[chisel3.core.CompileOptions]] while also supporting chained apply methods. In effect all "normal" methods that
-  *   you, as a user, will use in your designs, are converted to their "hidden", `do_*`, via macro transformations.
-  *   Without using macros here, only one of the above wanted behaviors is allowed (implicit passing and chained
-  *   applies)---the compiler interprets a chained apply as an explicit 'implicit' argument and will throw type errors.
-  *   <br>
-  *   <br>
+  *   These `do_X` methods are used to enable both implicit passing of SourceInfo and [[chisel3.core.CompileOptions]]
+  *   while also supporting chained apply methods. In effect all "normal" methods that you, as a user, will use in your
+  *   designs, are converted to their "hidden", `do_*`, via macro transformations. Without using macros here, only one
+  *   of the above wanted behaviors is allowed (implicit passing and chained applies)---the compiler interprets a
+  *   chained apply as an explicit 'implicit' argument and will throw type errors. <br> <br>
   *
-  *   The "normal", public-facing methods then take no [[SourceInfo]]. However, a macro transforms this public-facing
-  *   method into a call to an internal, hidden `do_*` that takes an explicit [[SourceInfo]] by inserting an
-  *   `implicitly[SourceInfo]` as the explicit argument.
-  * </p>
+  *   The "normal", public-facing methods then take no SourceInfo. However, a macro transforms this public-facing method
+  *   into a call to an internal, hidden `do_*` that takes an explicit SourceInfo by inserting an
+  *   `implicitly[SourceInfo]` as the explicit argument. </p>
   *
   * @groupprio SourceInfoTransformMacro 1001
   */
diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala
index d0f6f6bd..9071491b 100644
--- a/src/main/scala/chisel3/Driver.scala
+++ b/src/main/scala/chisel3/Driver.scala
@@ -151,7 +151,7 @@ object Driver extends BackendCompilationUtilities {
     * Emit the annotations of a circuit
     *
     * @param ir The circuit containing annotations to be emitted
-    * @param optName An optional filename (will use s"${ir.name}.json" otherwise)
+    * @param optName An optional filename (will use s"\${ir.name}.json" otherwise)
     */
   def dumpAnnotations(ir: Circuit, optName: Option[File]): File = {
     val f = optName.getOrElse(new File(ir.name + ".anno.json"))
diff --git a/src/main/scala/chisel3/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala
index 4ba762b5..c6458b9d 100644
--- a/src/main/scala/chisel3/util/Valid.scala
+++ b/src/main/scala/chisel3/util/Valid.scala
@@ -61,7 +61,7 @@ class Valid[+T <: Data](gen: T) extends Bundle {
   * }}}
   *
   * In addition to adding the `valid` bit, a [[Valid.fire]] method is also added that returns the `valid` bit. This
-  * provides a similarly named interface to [[DecoupledIO.fire]].
+  * provides a similarly named interface to [[DecoupledIO]]'s fire.
   *
   * @see [[Decoupled$ DecoupledIO Factory]]
   * @see [[Irrevocable$ IrrevocableIO Factory]]
diff --git a/src/main/scala/chisel3/util/experimental/BoringUtils.scala b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
index 67a6b6d0..a6f2d52a 100644
--- a/src/main/scala/chisel3/util/experimental/BoringUtils.scala
+++ b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
@@ -18,7 +18,7 @@ import chisel3.internal.Namespace
 class BoringUtilsException(message: String) extends Exception(message)
 
 /** Utilities for generating synthesizable cross module references that "bore" through the hierarchy. The underlying
-  * cross module connects are handled by FIRRTL's Wiring Transform ([[firrtl.passes.wiring.WiringTransform]]).
+  * cross module connects are handled by FIRRTL's Wiring Transform.
   *
   * Consider the following exmple where you want to connect a component in one module to a component in another. Module
   * `Constant` has a wire tied to `42` and `Expect` will assert unless connected to `42`:
diff --git a/src/main/scala/chisel3/util/experimental/Inline.scala b/src/main/scala/chisel3/util/experimental/Inline.scala
index 8ec5219b..753c36af 100644
--- a/src/main/scala/chisel3/util/experimental/Inline.scala
+++ b/src/main/scala/chisel3/util/experimental/Inline.scala
@@ -28,8 +28,8 @@ import firrtl.annotations.{CircuitName, ModuleName, ComponentName, Annotation}
   * class Bar extends Module with Internals with HasSub
   * /* The resulting instances will be:
   *  - Top
-  *  - Top.x$sub
-  *  - Top.y$sub
+  *  - Top.x\$sub
+  *  - Top.y\$sub
   *  - Top.z
   *  - Top.z.sub */
   * class Top extends Module with Internals {
diff --git a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
index 5e78fa34..2d23de38 100644
--- a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
+++ b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
@@ -18,7 +18,7 @@ import scala.collection.mutable
   * and the format of the file.
   * @param target        memory to load
   * @param fileName      name of input file
-  * @param hexOrBinary   use $readmemh or $readmemb, i.e. hex or binary text input, default is hex
+  * @param hexOrBinary   use \$readmemh or \$readmemb, i.e. hex or binary text input, default is hex
   */
 case class ChiselLoadMemoryAnnotation[T <: Data](
   target:      MemBase[T],
@@ -42,62 +42,72 @@ case class ChiselLoadMemoryAnnotation[T <: Data](
 }
 
 
+/** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file. This relies on
+  * Verilator and Verilog's `\$readmemh` or `\$readmemb`. The [[https://github.com/freechipsproject/treadle Treadle
+  * backend]] can also recognize this annotation and load memory at run-time.
+  *
+  * This annotation, when the FIRRTL compiler runs, triggers the [[LoadMemoryTransform]]. That will add Verilog
+  * directives to enable the specified memories to be initialized from files.
+  *
+  * ==Example module==
+  *
+  * Consider a simple Module containing a memory:
+  * {{{
+  * import chisel3._
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  * }
+  * }}}
+  *
+  * ==Above module with annotation==
+  *
+  * To load this memory from the file `/workspace/workdir/mem1.hex.txt` just add an import and annotate the memory:
+  * {{{
+  * import chisel3._
+  * import chisel3.util.experimental.loadMemoryFromFile   // <<-- new import here
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  *   loadMemoryFromFile(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
+  * }
+  * }}}
+  *
+  * ==Example file format==
+  *
+  * A memory file should consist of ASCII text in either hex or binary format. The following example shows such a
+  * file formatted to use hex:
+  * {{{
+  *   0
+  *   7
+  *   d
+  *  15
+  * }}}
+  *
+  * A binary file can be similarly constructed.
+  *
+  * @see
+  * [[https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/LoadMemoryFromFileSpec.scala
+  * LoadMemoryFromFileSpec.scala]] in the test suite for additional examples.
+  * @see Chisel3 Wiki entry on
+  * [[https://github.com/freechipsproject/chisel3/wiki/Chisel-Memories#loading-memories-in-simulation "Loading Memories
+  * in Simulation"]]
+  */
 object loadMemoryFromFile {
-  /** Use this annotation generator to load a memory from a text file by using verilator and
-    *  verilog's $readmemh or $readmemb.
-    *  The treadle backend can also recognize this annotation and load memory at run-time.
-    *
-    * This annotation triggers the [[LoadMemoryTransform]] which will take add the verilog directive to
-      * the relevant module by using the creating separate modules that are bound to the modules containing
-    * the memories to be loaded.
-    *
-    * ==Example module==
-    *
-    * Consider a simple Module containing a memory
-      * {{{
-        * import chisel3._
-        * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
-          *   val io = IO(new Bundle {
-            *     val address = Input(UInt(memoryType.getWidth.W))
-            *     val value   = Output(memoryType)
-            *   })
-          *   val memory = Mem(memoryDepth, memoryType)
-          *   io.value := memory(io.address)
-          * }
-        * }}}
-    *
-    * ==Above module with annotation==
-      *
-    * To load this memory from a file /workspace/workdir/mem1.hex.txt
-    * Just add an import and annotate the memory
-      * {{{
-        * import chisel3._
-        * import chisel3.util.experimental.loadMemoryFromFile   // <<-- new import here
-        * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
-          *   val io = IO(new Bundle {
-            *     val address = Input(UInt(memoryType.getWidth.W))
-            *     val value   = Output(memoryType)
-            *   })
-          *   val memory = Mem(memoryDepth, memoryType)
-          *   io.value := memory(io.address)
-          *   loadMemoryFromFile(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
-          * }
-        * }}}
-    *
-    * ==Example file format==
-      * A memory file should consist of ascii text in either hex or binary format
-    * Example (a file containing the decimal values 0, 7, 14, 21):
-      * {{{
-        *   0
-        *   7
-        *   d
-        *  15
-        * }}}
-    * Binary file is similarly constructed.
-    *
-    * ==More info==
-    * See the LoadMemoryFromFileSpec.scala in the test suite for more examples
-    * @see <a href="https://github.com/freechipsproject/chisel3/wiki/Chisel-Memories">Load Memories in the wiki</a>
+
+
+  /** Annotate a memory such that it can be initialized using a file
+    * @param memory the memory
+    * @param filename the file used for initialization
+    * @param hexOrBinary whether the file uses a hex or binary number representation
     */
   def apply[T <: Data](
     memory: MemBase[T],
@@ -108,15 +118,12 @@ object loadMemoryFromFile {
   }
 }
 
-/**
-  * This transform only is activated if verilog is being generated
-  * (determined by presence of the proper emit annotation)
-  * when activated it creates additional verilog files that contain
-  * modules bound to the modules that contain an initializable memory
+/** This transform only is activated if Verilog is being generated (determined by presence of the proper emit
+  * annotation) when activated it creates additional Verilog files that contain modules bound to the modules that
+  * contain an initializable memory
   *
-  * Currently the only non-verilog based simulation that can support loading
-  * memory from a file is treadle but it does not need this transform
-  * to do that.
+  * Currently the only non-Verilog based simulation that can support loading memory from a file is treadle but it does
+  * not need this transform to do that.
   */
 //scalastyle:off method.length
 class LoadMemoryTransform extends Transform {
@@ -129,8 +136,7 @@ class LoadMemoryTransform extends Transform {
 
   private val verilogEmitter:    VerilogEmitter = new VerilogEmitter
 
-  /**
-    * run the pass
+  /** run the pass
     * @param circuit the circuit
     * @param annotations all the annotations
     * @return
@@ -150,12 +156,10 @@ class LoadMemoryTransform extends Transform {
 
     val modulesByName = circuit.modules.collect { case module: firrtl.ir.Module =>  module.name -> module }.toMap
 
-    /**
-      * walk the module and for memories that have LoadMemory annotations
-      * generate the bindable modules for verilog emission
-      *
-      * @param myModule     module being searched for memories
-      */
+    /* Walk the module and for memories that are annotated with [[LoadMemoryAnnotation]]s generate the bindable modules for
+     * Verilog emission.
+     * @param myModule module being searched for memories
+     */
     def processModule(myModule: DefModule): DefModule = {
 
       def makePath(componentName: String): String = {