[chisel5] Fix FIRRTL doc warnings, make fatal

Fix all FIRRTL Scaladoc warnings and re-enable fatal warnings when
building the docs.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

build.sbt

@@ -319,6 +319,7 @@ lazy val chisel = (project in file("."))
   .dependsOn(firrtl)
   .aggregate(macros, core, plugin, firrtl)
   .settings(warningSuppression: _*)
+  .settings(fatalWarningsSettings: _*)
   .settings(
     mimaPreviousArtifacts := Set(),
     Test / scalacOptions ++= Seq("-language:reflectiveCalls"),
@@ -393,3 +394,4 @@ lazy val docs = project // new documentation project
       "BUILD_DIR" -> "docs-target" // build dir for mdoc programs to dump temp files
     )
   )
+  .settings(fatalWarningsSettings: _*)

core/src/main/scala/chisel3/internal/plugin/package.scala

@@ -38,7 +38,7 @@ package object plugin {
     * DO NOT USE in your normal Chisel code!!!
     *
     * @param names The names to use corresponding to interesting fields of the Product
-    * @param nameMe The [[Product]] to be named
+    * @param nameMe The [[scala.Product]] to be named
     * @tparam T The type of the thing to be named
     * @return The thing, but with each member named
     */

firrtl/src/main/scala/firrtl/RenameMap.scala

@@ -25,7 +25,6 @@ object RenameMap {
 
 /** Map old names to new names
   *
-  * Transforms that modify names should return a [[RenameMap]] with the [[CircuitState]]
   * These are mutable datastructures for convenience
   * @define noteSelfRename @note Self renames *will* be recorded
   * @define noteDistinct @note Rename to/tos will be made distinct

firrtl/src/main/scala/firrtl/options/DependencyManager.scala

@@ -35,7 +35,7 @@ trait DependencyManager[A, B <: TransformLike[A] with DependencyAPI[B]] extends
   private lazy val _targets: LinkedHashSet[Dependency[B]] = targets
     .foldLeft(new LinkedHashSet[Dependency[B]]()) { case (a, b) => a += b }
 
-  /** A sequence of [[firrtl.Transform]]s that have been run. Internally, this will be converted to an ordered set.
+  /** A sequence of [[TransformLike]]s that have been run. Internally, this will be converted to an ordered set.
     */
   def currentState: Seq[Dependency[B]]
   private lazy val _currentState: LinkedHashSet[Dependency[B]] = currentState

firrtl/src/main/scala/firrtl/options/phases/WriteOutputAnnotations.scala

@@ -24,9 +24,10 @@ import scala.collection.mutable
   *  1) Annotations which extend [[CustomFileEmission]] are written seperately to their prescribed
   *     destinations and replaced per [[[CustomFileEmission.replacements replacements]].
   *  2) All remaining annotations are written to destination specified by
-  *    [[StageOptions.annotationFileOut annotationFileOut]], iff the stage option is set, with the following exceptions:
+  *    [[StageOptions.annotationFileOut annotationFileOut]], iff the stage option is set, with the following exception:
   *    a) Annotations extending [[Unserializable]] are not written
-  *    b) Deleted annotations are not written unless [[StageOptions.writeDeleted writeDeleted]] is set
+  *    b) Annotations extending [[CustomFileEmission]] are written to the file they specify using the serialization they
+  *    define.  They show up in the output Annotation file using their "replacements", if one is specified.
   */
 class WriteOutputAnnotations extends Phase {
 

firrtl/src/main/scala/firrtl/stage/FirrtlAnnotations.scala

@@ -35,7 +35,6 @@ object OutputFileAnnotation extends HasShellOptions {
 /** Sets the info mode style
   *  - set with `--info-mode`
   * @param mode info mode name
-  * @note This cannote be directly converted to [[Parser.InfoMode]] as that depends on an optional [[FirrtlFileAnnotation]]
   */
 case class InfoModeAnnotation(modeName: String = "use") extends NoTargetAnnotation with FirrtlOption {
   require(

firrtl/src/main/scala/firrtl/stage/package.scala

@@ -5,17 +5,11 @@ package firrtl
 import firrtl.options.OptionsView
 import logger.LazyLogging
 
-/** The [[stage]] package provides an implementation of the FIRRTL compiler using the [[firrtl.options]] package. This
-  * primarily consists of:
-  *   - [[FirrtlStage]], the internal and external (command line) interface to the FIRRTL compiler
-  *   - A number of [[options.Phase Phase]]s that support and compartmentalize the individual operations of
-  *     [[FirrtlStage]]
-  *   - [[FirrtlOptions]], a class representing options that are necessary to drive the [[FirrtlStage]] and its
-  *     [[firrtl.options.Phase Phase]]s
+/** The [[stage]] package provides Stage/Phase infrastructure for FIRRTL compilers:
+  *   - A number of support [[options.Phase Phase]]s
+  *   - [[FirrtlOptions]], a class representing options common to FIRRTL compilers
   *   - [[FirrtlOptionsView]], a utility that constructs an [[options.OptionsView OptionsView]] of [[FirrtlOptions]]
   *     from an [[AnnotationSeq]]
-  *   - [[FirrtlCli]], the command line options that the [[FirrtlStage]] supports
-  *   - [[FirrtlStageUtils]] containing miscellaneous utilities for [[stage]]
   */
 package object stage {
   implicit object FirrtlOptionsView extends OptionsView[FirrtlOptions] with LazyLogging {

firrtl/src/main/scala/firrtl/stage/phases/AddDefaults.scala

@@ -7,9 +7,7 @@ import firrtl.options.{Phase, TargetDirAnnotation}
 import firrtl.transforms.BlackBoxTargetDirAnno
 import firrtl.stage.{FirrtlOptions, InfoModeAnnotation}
 
-/** [[firrtl.options.Phase Phase]] that adds default [[FirrtlOption]] [[firrtl.annotations.Annotation Annotation]]s.
-  * This is a part of the preprocessing done by [[FirrtlStage]].
-  */
+/** [[firrtl.options.Phase Phase]] that adds default [[FirrtlOption]] [[firrtl.annotations.Annotation Annotation]]s. */
 class AddDefaults extends Phase {
 
   override def prerequisites = Seq.empty

firrtl/src/main/scala/firrtl/stage/phases/Checks.scala

@@ -13,8 +13,7 @@ import firrtl.options.{Dependency, OptionsException, Phase}
   * [[AddDefaults]]).
   *
   * The intent of this approach is that after running this [[firrtl.options.Phase Phase]], a user can be absolutely
-  * certain that other [[firrtl.options.Phase Phase]]s or views will succeed. See [[FirrtlStage]] for a list of
-  * [[firrtl.options.Phase Phase]] that commonly run before this.
+  * certain that other [[firrtl.options.Phase Phase]]s or views will succeed.
   */
 class Checks extends Phase {
 

root-doc.txt

@@ -3,7 +3,7 @@ This is the documentation for Chisel.
 == Package structure ==
 
 The [[chisel3]] package presents the public API of Chisel.
-It contains the concrete core types [[chisel3.UInt `UInt`]], [[chisel3.SInt `SInt`]], [[chisel3.Bool `Bool`]], [[chisel3.experimental.FixedPoint `FixedPoint`]], [[chisel3.Clock `Clock`]], and [[chisel3.Reg `Reg`]],
+It contains the concrete core types [[chisel3.UInt `UInt`]], [[chisel3.SInt `SInt`]], [[chisel3.Bool `Bool`]], [[chisel3.Clock `Clock`]], and [[chisel3.Reg `Reg`]],
 the abstract types [[chisel3.Bits `Bits`]], [[chisel3.Aggregate `Aggregate`]], and [[chisel3.Data `Data`]],
 and the aggregate types [[chisel3.Bundle `Bundle`]] and [[chisel3.Vec `Vec`]].
 

src/main/scala/chisel3/stage/phases/Emitter.scala

@@ -2,7 +2,7 @@
 
 package chisel3.stage.phases
 
-import firrtl.{AnnotationSeq, EmittedFirrtlCircuit, EmittedFirrtlCircuitAnnotation}
+import firrtl.AnnotationSeq
 import firrtl.options.{Dependency, Phase, StageOptions}
 import firrtl.options.Viewer.view
 
@@ -12,14 +12,9 @@ import chisel3.stage.{ChiselCircuitAnnotation, ChiselOptions}
 import java.io.{File, FileWriter}
 
 /** Emit a [[chisel3.stage.ChiselCircuitAnnotation]] to a file if a [[chisel3.stage.ChiselOutputFileAnnotation]] is
-  * present. A deleted [[firrtl.EmittedFirrtlCircuitAnnotation]] is added.
+  * present.
   *
-  * @todo This should be switched to support correct emission of multiple circuits to multiple files. The API should
-  * likely mirror how the [[firrtl.stage.phases.Compiler]] parses annotations into "global" annotations and
-  * left-associative per-circuit annotations.
-  * @todo The use of the deleted [[firrtl.EmittedFirrtlCircuitAnnotation]] is a kludge to provide some breadcrumbs such
-  * that the emitted CHIRRTL can be provided back to the old Driver. This should be removed or a better solution
-  * developed.
+  * @todo This should be switched to support correct emission of multiple circuits to multiple files.
   */
 class Emitter extends Phase {
 

src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala

@@ -35,8 +35,8 @@ private case class ChiselLoadMemoryAnnotation[T <: Data](
 /** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file as a bind module. This relies on
   * Verilator and Verilog's `\$readmemh` or `\$readmemb`.
   *
-  * 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.
+  * This annotation, when a FIRRTL compiler runs will add Verilog directives to enable the specified memories to be
+  * initialized from files.
   *
   * ==Example module==
   *

src/main/scala/circt/stage/Annotations.scala

@@ -8,7 +8,7 @@ import firrtl.options.{CustomFileEmission, HasShellOptions, OptionsException, Sh
 import firrtl.options.Viewer.view
 import firrtl.stage.FirrtlOptions
 
-/** An option consumed by [[circt.stage.CIRCTStage CIRCTStage]] */
+/** An option used to construct a [[circt.stage.CIRCTOptions CIRCTOptions]] */
 sealed trait CIRCTOption extends Unserializable { this: Annotation => }
 
 object PreserveAggregate extends HasShellOptions {

src/main/scala/circt/stage/ChiselStage.scala

@@ -32,8 +32,6 @@ trait CLI { this: Shell =>
 }
 
 /** Entry point for running Chisel with the CIRCT compiler.
-  *
-  * This is intended to be a replacement for [[chisel3.stage.ChiselStage]].
   *
   * @note The companion object, [[ChiselStage$]], has a cleaner API for compiling and returning a string.
   */

src/main/scala/circt/stage/phases/AddImplicitOutputFile.scala

@@ -8,19 +8,15 @@ import firrtl.AnnotationSeq
 import firrtl.options.{Dependency, Phase, Viewer}
 import firrtl.stage.{FirrtlOptions, OutputFileAnnotation}
 
-/** [[firrtl.options.Phase Phase]] that adds an [[OutputFileAnnotation]] if one does not already exist.
+/** [[firrtl.options.Phase Phase]] that adds an [[firrtl.stage.OutputFileAnnotation OutputFileAnnotation]] if one does
+  * not already exist.
   *
-  * To determine the [[OutputFileAnnotation]], the following precedence is used. Whichever happens first succeeds:
-  *  - Do nothing if an [[OutputFileAnnotation]] or [[EmitAllModulesAnnotation]] exist
+  * To determine the [[firrtl.stage.OutputFileAnnotation OutputFileAnnotation]], the following precedence is
+  * used. Whichever happens first succeeds:
+  *  - Do nothing if an [[firrtl.stage.OutputFileAnnotation OutputFileAnnotation]] "--split-verilog" was specified
   *  - Use the main in the first discovered [[firrtl.stage.FirrtlCircuitAnnotation FirrtlCircuitAnnotation]] (see note
   *    below)
   *  - Use "a"
-  *
-  * The file suffix may or may not be specified, but this may be arbitrarily changed by the [[Emitter]].
-  *
-  * @note This [[firrtl.options.Phase Phase]] has a dependency on [[AddCircuit]]. Only a
-  * [[firrtl.stage.FirrtlCircuitAnnotation FirrtlCircuitAnnotation]] will be used to implicitly set the
-  * [[OutputFileAnnotation]] (not other [[firrtl.stage.CircuitOption CircuitOption]] subclasses).
   */
 class AddImplicitOutputFile extends Phase {
 
@@ -30,7 +26,7 @@ class AddImplicitOutputFile extends Phase {
 
   override def invalidates(a: Phase) = false
 
-  /** Add an [[OutputFileAnnotation]] to an [[AnnotationSeq]] */
+  /** Add an [[firrtl.stage.OutputFileAnnotation OutputFileAnnotation]] to an [[firrtl.AnnotationSeq AnnotationSeq]] */
   def transform(annotations: AnnotationSeq): AnnotationSeq =
     annotations.collectFirst { case _: OutputFileAnnotation | SplitVerilog => annotations }.getOrElse {
       val topName = Viewer[FirrtlOptions]

src/main/scala/circt/stage/phases/CIRCT.scala

@@ -115,10 +115,7 @@ private[this] object Exceptions {
 
 }
 
-/** A phase that calls and runs CIRCT, specifically `firtool`, while preserving an `AnnotationSeq` API.
-  *
-  * This is analogous to [[firrtl.stage.phases.Compiler]].
-  */
+/** A phase that calls and runs CIRCT, specifically `firtool`, while preserving an [[firrtl.AnnotationSeq AnnotationSeq]] API. */
 class CIRCT extends Phase {
 
   import Helpers._