Get rid of warnings in / doc build (#3041)

* Get rid of warnings in / doc build
  Many `[[...]]` dont work so replace with back-ticks
  Printable docs are very problematic, use Warning suppression for those
* Enable fatal warnings in CI for ScalaDoc generation

Co-authored-by: Jack Koenig <koenig@sifive.com>

Author: chick

.github/workflows/test.yml

@@ -133,7 +133,7 @@ jobs:
         uses: ./.github/workflows/install-circt
         #TODO: make the microsite building include building ScalaDoc
       - name: Build the docs
-        run: sbt -DdisableFatalWarnings doc
+        run: sbt doc
       - name: Build the microsite
         run: make -C website
         env:

build.sbt

@@ -56,7 +56,8 @@ lazy val warningSuppression = Seq(
     "msg=Importing from firrtl:s",
     "msg=migration to the MLIR:s",
     "msg=method hasDefiniteSize in trait IterableOnceOps is deprecated:s",  // replacement `knownSize` is not in 2.12
-    "msg=object JavaConverters in package collection is deprecated:s"
+    "msg=object JavaConverters in package collection is deprecated:s",
+    "msg=undefined in comment for method cf in class PrintableHelper:s"
   ).mkString(",")
 )
 
@@ -110,6 +111,7 @@ lazy val chiselSettings = Seq(
 )
 
 autoCompilerPlugins := true
+autoAPIMappings := true
 
 // Plugin must be fully cross-versioned (published for Scala minor version)
 // The plugin only works in Scala 2.12+
@@ -318,7 +320,3 @@ lazy val docs = project // new documentation project
     )
   )
   .settings(fatalWarningsSettings: _*)
-
-addCommandAlias("com", "all compile")
-addCommandAlias("lint", "; compile:scalafix --check ; test:scalafix --check")
-addCommandAlias("fix", "all compile:scalafix test:scalafix")

core/src/main/scala/chisel3/Aggregate.scala

@@ -227,7 +227,7 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Seq.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of `that` may end up driving sub-elements of `this`
     *  - Complicated semantics, will likely be deprecated in the future
     *
     * For Chisel._, emits the FIRRTL.<- operator
@@ -249,7 +249,7 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Vec.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of `that` may end up driving sub-elements of `this`
     *  - See docs/src/explanations/connection-operators.md for details
     *
     * For Chisel._, emits the FIRRTL.<- operator
@@ -1159,11 +1159,11 @@ abstract class Record(private[chisel3] implicit val compileOptions: CompileOptio
     clone
   }
 
-  /** The collection of [[Data]]
+  /** The collection of [[chisel3.Data]]
     *
     * This underlying datastructure is a ListMap because the elements must
     * remain ordered for serialization/deserialization. Elements added later
-    * are higher order when serialized (this is similar to [[Vec]]). For example:
+    * are higher order when serialized (this is similar to `Vec`). For example:
     * {{{
     *   // Assume we have some type MyRecord that creates a Record from the ListMap
     *   val record = MyRecord(ListMap("fizz" -> UInt(16.W), "buzz" -> UInt(16.W)))

core/src/main/scala/chisel3/Annotation.scala

@@ -28,11 +28,7 @@ trait ChiselMultiAnnotation {
   def toFirrtl: Seq[Annotation]
 }
 
-/** 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\.RawModule)* Driver.execute]].
-  * Automatic Transform instantiation is *not* supported when the Circuit and Annotations are serialized before invoking
-  * FIRRTL.
+/** Mixin for [[ChiselAnnotation]] that instantiates an associated Transform when this Annotation is present
   */
 trait RunFirrtlTransform extends ChiselAnnotation {
   def transformClass: Class[_ <: Transform]
@@ -78,12 +74,7 @@ object annotate {
   *  io.out(1) := fullAdder(io.a, io.b, "mod2")
   * }
   * }}}
-  *
-  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
-  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
   */
-
 object doNotDedup {
 
   /** Marks a module to be ignored in Dedup Transform in Firrtl

core/src/main/scala/chisel3/Bits.scala

@@ -374,10 +374,10 @@ sealed abstract class Bits(private[chisel3] val width: Width) extends Element wi
   /** @group SourceInfoTransformMacro */
   def do_asSInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt
 
-  /** Reinterpret this $coll as a [[FixedPoint]].
+  /** Reinterpret this $coll as a `FixedPoint`.
     *
     * @note The value is not guaranteed to be preserved. For example, a [[UInt]] of width 3 and value 7 (0b111) would
-    * become a [[FixedPoint]] with value -1. The interpretation of the number is also affected by the specified binary
+    * become a `FixedPoint` with value -1. The interpretation of the number is also affected by the specified binary
     * point. '''Caution is advised!'''
     */
   @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1331,7 +1331,7 @@ package experimental {
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
     def binaryPoint: BinaryPoint
 
-    /** Return the [[Double]] value of this instance if it is a Literal
+    /** Return the `Double` value of this instance if it is a Literal
       * @note this method may throw an exception if the literal value won't fit in a Double
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1348,7 +1348,7 @@ package experimental {
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
     def litToDouble: Double = litToDoubleOption.get
 
-    /** Return the [[BigDecimal]] value of this instance if it is a Literal
+    /** Return the [[scala.math.BigDecimal]] value of this instance if it is a Literal
       * @note this method may throw an exception if the literal value won't fit in a BigDecimal
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1360,7 +1360,7 @@ package experimental {
       }
     }
 
-    /** Return the [[BigDecimal]] value of this instance assuming it is a literal (convenience method)
+    /** Return the [[scala.math.BigDecimal]] value of this instance assuming it is a literal (convenience method)
       * @return
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1860,7 +1860,7 @@ package experimental {
     *   val one = 1.I
     *   val six = Seq.fill(6)(one).reduce(_ + _)
     * }}}
-    * A UInt computed in this way would require a [[Width]]
+    * A UInt computed in this way would require a `Width`
     * binary point
     * The width and binary point may be inferred.
     *

core/src/main/scala/chisel3/Data.scala

@@ -723,7 +723,7 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Vec.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of that` may end up driving sub-elements of `this`
     *  - Complicated semantics, hard to write quickly, will likely be deprecated in the future
     *
     * For Chisel._, emits the FIRRTL.<- operator

core/src/main/scala/chisel3/Module.scala

@@ -401,8 +401,8 @@ package experimental {
 
     /** The desired name of this module (which will be used in generated FIRRTL IR or Verilog).
       *
-      * The name of a module approximates the behavior of the Java Reflection [[`getSimpleName` method
-      * https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getSimpleName--]] with some modifications:
+      * The name of a module approximates the behavior of the Java Reflection `getSimpleName` method
+      * https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getSimpleName-- with some modifications:
       *
       * - Anonymous modules will get an `"_Anon"` tag
       * - Modules defined in functions will use their class name and not a numeric name

core/src/main/scala/chisel3/VerificationStatement.scala

@@ -64,7 +64,7 @@ object assert extends VerifPrintMacrosDoc {
     * @param cond condition, assertion fires (simulation fails) on a rising clock edge when false and reset is not asserted
     * @param message optional chisel Printable type message
     *
-    * @note See [[printf.apply(fmt:Printable)]] for documentation on printf using Printables
+    * @note See [[printf.apply(pable:chisel3\.Printable)*]] for documentation on printf using Printables
     * @note currently cannot be used in core Chisel / libraries because macro
     * defs need to be compiled first and the SBT project is not set up to do
     * that
@@ -239,7 +239,7 @@ object assume extends VerifPrintMacrosDoc {
     * @param cond condition, assertion fires (simulation fails) when false
     * @param message optional Printable type message when the assertion fires
     *
-    * @note See [[printf.apply(fmt:Printable]] for documentation on printf using Printables
+    * @note See [[printf.apply(pable:chisel3\.Printable)*]] for documentation on printf using Printables
     */
   def apply(
     cond:    Bool,

core/src/main/scala/chisel3/connectable/Connectable.scala

@@ -125,7 +125,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    * - Connecting two [[util.DecoupledIO]]'s would connect `bits`, `valid`, AND `ready` from producer to consumer (despite `ready` being flipped)
+    * - Connecting two `util.DecoupledIO`'s would connect `bits`, `valid`, AND `ready` from producer to consumer (despite `ready` being flipped)
     * - Functionally equivalent to chisel3.:=, but different than Chisel.:=
     *
     * @group connection
@@ -143,7 +143,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    *  - Connecting two [[util.DecoupledIO]]'s would connect `bits` and `valid` from producer to consumer, but leave `ready` unconnected
+    *  - Connecting two `util.DecoupledIO`'s would connect `bits` and `valid` from producer to consumer, but leave `ready` unconnected
     *
     * @group connection
     *
@@ -160,7 +160,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    *  - Connecting two [[util.DecoupledIO]]'s would connect `ready` from consumer to producer, but leave `bits` and `valid` unconnected
+    *  - Connecting two `util.DecoupledIO`'s would connect `ready` from consumer to producer, but leave `bits` and `valid` unconnected
     *
     * @group connection
     *
@@ -182,7 +182,7 @@ object Connectable {
     * - An additional type restriction is that all relative orientations of `consumer` and `producer` must match exactly.
     *
     * Additional notes:
-    *  - Connecting two wires of [[util.DecoupledIO]] chisel type would connect `bits` and `valid` from producer to consumer, and `ready` from consumer to producer.
+    *  - Connecting two wires of `util.DecoupledIO` chisel type would connect `bits` and `valid` from producer to consumer, and `ready` from consumer to producer.
     *  - If the types of consumer and producer also have identical relative flips, then we can emit FIRRTL.<= as it is a stricter version of chisel3.:<>=
     *  - "turk-duck-en" is a dish where a turkey is stuffed with a duck, which is stuffed with a chicken; `:<>=` is a `:=` stuffed with a `<>`
     *

core/src/main/scala/chisel3/dontTouch.scala

@@ -19,9 +19,6 @@ import firrtl.transforms.DontTouchAnnotation
   *   dontTouch(dead) // Marking it as such will preserve it
   * }
   * }}}
-  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
-  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
   * @note Because this is an optimization barrier, constants will not be propagated through a signal marked as
   * dontTouch.
   */

core/src/main/scala/chisel3/experimental/Trace.scala

@@ -59,7 +59,7 @@ object Trace {
     def duplicate(n: T): Annotation = this.copy(target = n)
   }
 
-  /** Get [[CompleteTarget]] of the target `x` for `annos`.
+  /** Get `CompleteTarget` of the target `x` for `annos`.
     * This API can be used to find the final reference to a signal or module which is marked by `traceName`
     */
   def finalTarget(annos: AnnotationSeq)(x: HasId): Seq[CompleteTarget] = finalTargetMap(annos)

core/src/main/scala/chisel3/experimental/dataview/DataProduct.scala

@@ -92,7 +92,7 @@ object DataProduct extends LowPriorityDataProduct {
     }
   }
 
-  /** [[DataProduct]] implementation for any [[Tuple2]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple2]] where each field has an implementation of `DataProduct`. */
   implicit def tuple2DataProduct[A: DataProduct, B: DataProduct]: DataProduct[(A, B)] = new DataProduct[(A, B)] {
     def dataIterator(tup: (A, B), path: String): Iterator[(Data, String)] = {
       val dpa = implicitly[DataProduct[A]]
@@ -102,7 +102,7 @@ object DataProduct extends LowPriorityDataProduct {
     }
   }
 
-  /** [[DataProduct]] implementation for any [[Tuple3]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple3]] where each field has an implementation of `DataProduct`. */
   implicit def tuple3DataProduct[A: DataProduct, B: DataProduct, C: DataProduct]: DataProduct[(A, B, C)] =
     new DataProduct[(A, B, C)] {
       def dataIterator(tup: (A, B, C), path: String): Iterator[(Data, String)] = {
@@ -114,7 +114,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple4]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple4]] where each field has an implementation of `DataProduct`. */
   implicit def tuple4DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -135,7 +135,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple5]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple5]] where each field has an implementation of `DataProduct`. */
   implicit def tuple5DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -159,7 +159,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple6]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple6]] where each field has an implementation of `DataProduct`. */
   implicit def tuple6DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -186,7 +186,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple7]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple7]] where each field has an implementation of `DataProduct`. */
   implicit def tuple7DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -216,7 +216,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple8]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple8]] where each field has an implementation of `DataProduct`. */
   implicit def tuple8DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -249,7 +249,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple9]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple9]] where each field has an implementation of `DataProduct`. */
   implicit def tuple9DataProduct[
     A: DataProduct,
     B: DataProduct,
@@ -285,7 +285,7 @@ object DataProduct extends LowPriorityDataProduct {
       }
     }
 
-  /** [[DataProduct]] implementation for any [[Tuple9]] where each field has an implementation of `DataProduct`. */
+  /** [[DataProduct]] implementation for any [[scala.Tuple9]] where each field has an implementation of `DataProduct`. */
   implicit def tuple10DataProduct[
     A: DataProduct,
     B: DataProduct,

core/src/main/scala/chisel3/experimental/dataview/DataView.scala

@@ -170,7 +170,7 @@ object DataView {
     )
   }
 
-  /** Provides implementations of [[DataView]] for [[Tuple2]] to [[HWTuple2]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple2]]  to [[HWTuple2]] */
   implicit def tuple2DataView[T1: DataProduct, T2: DataProduct, V1 <: Data, V2 <: Data](
     implicit v1: DataView[T1, V1],
     v2:          DataView[T2, V2],
@@ -184,7 +184,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple3]] to [[HWTuple3]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple3]] to [[HWTuple3]] */
   implicit def tuple3DataView[T1: DataProduct, T2: DataProduct, T3: DataProduct, V1 <: Data, V2 <: Data, V3 <: Data](
     implicit v1: DataView[T1, V1],
     v2:          DataView[T2, V2],
@@ -199,7 +199,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple4]] to [[HWTuple4]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple4]] to [[HWTuple4]] */
   implicit def tuple4DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -227,7 +227,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple5]] to [[HWTuple5]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple5]] to [[HWTuple5]] */
   implicit def tuple5DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -272,7 +272,7 @@ object DataView {
     )
   }
 
-  /** Provides implementations of [[DataView]] for [[Tuple6]] to [[HWTuple6]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple6]] to [[HWTuple6]] */
   implicit def tuple6DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -320,7 +320,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple7]] to [[HWTuple7]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple7]] to [[HWTuple7]] */
   implicit def tuple7DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -373,7 +373,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple8]] to [[HWTuple8]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple8]] to [[HWTuple8]] */
   implicit def tuple8DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -431,7 +431,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple9]] to [[HWTuple9]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple9]] to [[HWTuple9]] */
   implicit def tuple9DataView[
     T1: DataProduct,
     T2: DataProduct,
@@ -494,7 +494,7 @@ object DataView {
       }
     )
 
-  /** Provides implementations of [[DataView]] for [[Tuple10]] to [[HWTuple10]] */
+  /** Provides implementations of [[DataView]] for [[scala.Tuple10]] to [[HWTuple10]] */
   implicit def tuple10DataView[
     T1:  DataProduct,
     T2:  DataProduct,