Merge pull request #873 from seldridge/issue-872

API Documentation Improvements

12 files changed, 787 insertions, 123 deletions

diff --git a/build.sbt b/build.sbt
index cf41a0ab..d3049939 100644
--- a/build.sbt
+++ b/build.sbt
@@ -140,6 +140,8 @@ lazy val chisel = (project in file(".")).
     scalacOptions in Test ++= Seq("-language:reflectiveCalls"),
     scalacOptions in Compile in doc ++= Seq(
       "-diagrams",
+      "-groups",
+      "-skip-packages", "chisel3.internal",
       "-diagrams-max-classes", "25",
       "-doc-version", version.value,
       "-doc-title", name.value,
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
index 235b1d5a..f47b33d9 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
@@ -10,6 +10,7 @@ import chisel3.internal._
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo._
+import chisel3.SourceInfoDoc
 
 /** An abstract class for data types that solely consist of (are an aggregate
   * of) other Data objects.
@@ -97,7 +98,7 @@ sealed abstract class Aggregate extends Data {
   }
 }
 
-trait VecFactory {
+trait VecFactory extends SourceInfoDoc {
   /** Creates a new [[Vec]] with `n` entries of the specified data type.
     *
     * @note elements are NOT assigned by default and have no value
@@ -209,6 +210,7 @@ sealed class Vec[T <: Data] private[core] (gen: => T, val length: Int)
     */
   override def apply(p: UInt): T = macro CompileOptionsTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_apply(p: UInt)(implicit compileOptions: CompileOptions): T = {
     requireIsHardware(p, "vec index")
     val port = gen
@@ -259,7 +261,7 @@ sealed class Vec[T <: Data] private[core] (gen: => T, val length: Int)
   }
 }
 
-object VecInit {
+object VecInit extends SourceInfoDoc {
   /** Creates a new [[Vec]] composed of elements of the input Seq of [[Data]]
     * nodes.
     *
@@ -271,6 +273,7 @@ object VecInit {
     */
   def apply[T <: Data](elts: Seq[T]): Vec[T] = macro VecTransform.apply_elts
 
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: Data](elts: Seq[T])(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] = {
     // REVIEW TODO: this should be removed in favor of the apply(elts: T*)
     // varargs constructor, which is more in line with the style of the Scala
@@ -310,6 +313,7 @@ object VecInit {
     */
   def apply[T <: Data](elt0: T, elts: T*): Vec[T] = macro VecTransform.apply_elt0
 
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: Data](elt0: T, elts: T*)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] =
     apply(elt0 +: elts.toSeq)
 
@@ -323,6 +327,7 @@ object VecInit {
     */
   def tabulate[T <: Data](n: Int)(gen: (Int) => T): Vec[T] = macro VecTransform.tabulate
 
+  /** @group SourceInfoTransformMacro */
   def do_tabulate[T <: Data](n: Int)(gen: (Int) => T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] =
     apply((0 until n).map(i => gen(i)))
 }
@@ -330,9 +335,10 @@ object VecInit {
 /** A trait for [[Vec]]s containing common hardware generators for collection
   * operations.
   */
-trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
+trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId with SourceInfoDoc {
   def apply(p: UInt): T = macro CompileOptionsTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_apply(p: UInt)(implicit compileOptions: CompileOptions): T
 
   // IndexedSeq has its own hashCode/equals that we must not use
@@ -353,6 +359,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def forall(p: T => Bool): Bool = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_forall(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     (this map p).fold(true.B)(_ && _)
 
@@ -360,6 +367,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def exists(p: T => Bool): Bool = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_exists(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     (this map p).fold(false.B)(_ || _)
 
@@ -368,6 +376,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def contains(x: T)(implicit ev: T <:< UInt): Bool = macro VecTransform.contains
 
+  /** @group SourceInfoTransformMacro */
   def do_contains(x: T)(implicit sourceInfo: SourceInfo, ev: T <:< UInt, compileOptions: CompileOptions): Bool =
     this.exists(_ === x)
 
@@ -375,6 +384,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def count(p: T => Bool): UInt = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_count(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     SeqUtils.count(this map p)
 
@@ -387,6 +397,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def indexWhere(p: T => Bool): UInt = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_indexWhere(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     SeqUtils.priorityMux(indexWhereHelper(p))
 
@@ -394,6 +405,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def lastIndexWhere(p: T => Bool): UInt = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_lastIndexWhere(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     SeqUtils.priorityMux(indexWhereHelper(p).reverse)
 
@@ -409,6 +421,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
     */
   def onlyIndexWhere(p: T => Bool): UInt = macro SourceInfoTransform.pArg
 
+  /** @group SourceInfoTransformMacro */
   def do_onlyIndexWhere(p: T => Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     SeqUtils.oneHotMux(indexWhereHelper(p))
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 10b6ec8e..e9458446 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -14,8 +14,10 @@ import chisel3.internal.firrtl.PrimOp._
 
 //scalastyle:off method.name
 
-/** Element is a leaf data type: it cannot contain other Data objects. Example
-  * uses are for representing primitive data types, like integers and bits.
+/** Element is a leaf data type: it cannot contain other [[Data]] objects. Example uses are for representing primitive
+  * data types, like integers and bits.
+  *
+  * @define coll element
   */
 abstract class Element(private[chisel3] val width: Width) extends Data {
   private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection) {
@@ -43,26 +45,31 @@ abstract class Element(private[chisel3] val width: Width) extends Data {
   }
 }
 
-/** Exists to unify common interfaces of [[Bits]] and [[Reset]]
-  * Workaround because macros cannot override abstract methods
+/** Exists to unify common interfaces of [[Bits]] and [[Reset]].
+  *
+  * @note This is a workaround because macros cannot override abstract methods.
   */
 private[chisel3] sealed trait ToBoolable extends Element {
 
-  /** Casts this object to a [[Bool]]
+  /** Casts this $coll to a [[Bool]]
     *
-    * @note Width must be known and equal to 1
+    * @note The width must be known and equal to 1
     */
   final def toBool(): Bool = macro SourceInfoWhiteboxTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_toBool(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 }
 
-/** A data type for values represented by a single bitvector. Provides basic
-  * bitwise operations.
+/** A data type for values represented by a single bitvector. This provides basic bitwise operations.
+  *
+  * @groupdesc Bitwise Bitwise hardware operators
+  * @define coll [[Bits]]
+  * @define sumWidthInt    @note The width of the returned $coll is `width of this` + `that`.
+  * @define sumWidth       @note The width of the returned $coll is `width of this` + `width of that`.
+  * @define unchangedWidth @note The width of the returned $coll is unchanged, i.e., the `width of this`.
   */
-//scalastyle:off number.of.methods
-sealed abstract class Bits(width: Width)
-    extends Element(width) with ToBoolable {
+sealed abstract class Bits(width: Width) extends Element(width) with ToBoolable { //scalastyle:off number.of.methods
   // TODO: perhaps make this concrete?
   // Arguments for: self-checking code (can't do arithmetic on bits)
   // Arguments against: generates down to a FIRRTL UInt anyways
@@ -99,9 +106,23 @@ sealed abstract class Bits(width: Width)
     case _ => super.ref
   }
 
+  /** Tail operator
+    *
+    * @param n the number of bits to remove
+    * @return This $coll with the `n` most significant bits removed.
+    * @group Bitwise
+    */
   final def tail(n: Int): UInt = macro SourceInfoTransform.nArg
+
+  /** Head operator
+    *
+    * @param n the number of bits to take
+    * @return The `n` most significant bits of this $coll
+    * @group Bitwise
+    */
   final def head(n: Int): UInt = macro SourceInfoTransform.nArg
 
+  /** @group SourceInfoTransformMacro */
   def do_tail(n: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     val w = width match {
       case KnownWidth(x) =>
@@ -112,7 +133,7 @@ sealed abstract class Bits(width: Width)
     binop(sourceInfo, UInt(width = w), TailOp, n)
   }
 
-
+  /** @group SourceInfoTransformMacro */
   def do_head(n: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     width match {
       case KnownWidth(x) => require(x >= n, s"Can't head($n) for width $x < $n")
@@ -121,11 +142,14 @@ sealed abstract class Bits(width: Width)
     binop(sourceInfo, UInt(Width(n)), HeadOp, n)
   }
 
-  /** Returns the specified bit on this wire as a [[Bool]], statically
-    * addressed.
+  /** Returns the specified bit on this $coll as a [[Bool]], statically addressed.
+    *
+    * @param x an index
+    * @return the specified bit
     */
   final def apply(x: BigInt): Bool = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   final def do_apply(x: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     if (x < 0) {
       Builder.error(s"Negative bit indices are illegal (got $x)")
@@ -140,36 +164,44 @@ sealed abstract class Bits(width: Width)
     }
   }
 
-  /** Returns the specified bit on this wire as a [[Bool]], statically
-    * addressed.
+  /** Returns the specified bit on this $coll as a [[Bool]], statically addressed.
     *
-    * @note convenience method allowing direct use of Ints without implicits
+    * @param x an index
+    * @return the specified bit
+    * @note convenience method allowing direct use of [[scala.Int]] without implicits
     */
   final def apply(x: Int): Bool = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   final def do_apply(x: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = apply(BigInt(x))
 
-  /** Returns the specified bit on this wire as a [[Bool]], dynamically
-    * addressed.
+  /** Returns the specified bit on this wire as a [[Bool]], dynamically addressed.
+    *
+    * @param x a hardware component whose value will be used for dynamic addressing
+    * @return the specified bit
     */
   final def apply(x: UInt): Bool = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   final def do_apply(x: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     val theBits = this >> x
     theBits(0)
   }
 
-  /** Returns a subset of bits on this wire from `hi` to `lo` (inclusive),
-    * statically addressed.
+  /** Returns a subset of bits on this $coll from `hi` to `lo` (inclusive), statically addressed.
     *
     * @example
     * {{{
     * myBits = 0x5 = 0b101
     * myBits(1,0) => 0b01  // extracts the two least significant bits
     * }}}
+    * @param x the high bit
+    * @param y the low bit
+    * @return a hardware component contain the requested bits
     */
   final def apply(x: Int, y: Int): UInt = macro SourceInfoTransform.xyArg
 
+  /** @group SourceInfoTransformMacro */
   final def do_apply(x: Int, y: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     if (x < y || y < 0) {
       Builder.error(s"Invalid bit range ($x,$y)")
@@ -186,8 +218,20 @@ sealed abstract class Bits(width: Width)
   }
 
   // REVIEW TODO: again, is this necessary? Or just have this and use implicits?
+  /** Returns a subset of bits on this $coll from `hi` to `lo` (inclusive), statically addressed.
+    *
+    * @example
+    * {{{
+    * myBits = 0x5 = 0b101
+    * myBits(1,0) => 0b01  // extracts the two least significant bits
+    * }}}
+    * @param x the high bit
+    * @param y the low bit
+    * @return a hardware component contain the requested bits
+    */
   final def apply(x: BigInt, y: BigInt): UInt = macro SourceInfoTransform.xyArg
 
+  /** @group SourceInfoTransformMacro */
   final def do_apply(x: BigInt, y: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     apply(x.toInt, y.toInt)
 
@@ -214,96 +258,134 @@ sealed abstract class Bits(width: Width)
     pushOp(DefPrim(sourceInfo, Bool(), op, this.ref))
   }
 
-  /** Returns this wire zero padded up to the specified width.
+  /** Pad operator
     *
-    * @note for SInts only, this does sign extension
+    * @param that the width to pad to
+    * @return this @coll zero padded up to width `that`. If `that` is less than the width of the original component,
+    * this method returns the original component.
+    * @note For [[SInt]]s only, this will do sign extension.
+    * @group Bitwise
     */
   final def pad(that: Int): this.type = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_pad(that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): this.type = this.width match {
     case KnownWidth(w) if w >= that => this
     case _ => binop(sourceInfo, cloneTypeWidth(this.width max Width(that)), PadOp, that)
   }
 
-  /** Returns this wire bitwise-inverted. */
+  /** Bitwise inversion operator
+    *
+    * @return this $coll with each bit inverted
+    * @group Bitwise
+    */
   final def unary_~ (): Bits = macro SourceInfoWhiteboxTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-
-  /** Shift left operation */
+  /** Static left shift operator
+    *
+    * @param that an amount to shift by
+    * @return this $coll with `that` many zeros concatenated to its least significant end
+    * $sumWidthInt
+    * @group Bitwise
+    */
   // REVIEW TODO: redundant
   // REVIEW TODO: should these return this.type or Bits?
   final def << (that: BigInt): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_<< (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Returns this wire statically left shifted by the specified amount,
-    * inserting zeros into the least significant bits.
+  /** Static left shift operator
     *
-    * The width of the output is `other` larger than the input.
+    * @param that an amount to shift by
+    * @return this $coll with `that` many zeros concatenated to its least significant end
+    * $sumWidthInt
+    * @group Bitwise
     */
   final def << (that: Int): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_<< (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Returns this wire dynamically left shifted by the specified amount,
-    * inserting zeros into the least significant bits.
+  /** Dynamic left shift operator
     *
-    * The width of the output is `pow(2, width(other))` larger than the input.
+    * @param that a hardware component
+    * @return this $coll dynamically shifted left by `that` many places, shifting in zeros from the right
+    * @note The width of the returned $coll is `width of this + pow(2, width of that)`.
+    * @group Bitwise
     */
   final def << (that: UInt): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_<< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Shift right operation */
+  /** Static right shift operator
+    *
+    * @param that an amount to shift by
+    * @return this $coll with `that` many least significant bits truncated
+    * $unchangedWidth
+    * @group Bitwise
+    */
   // REVIEW TODO: redundant
   final def >> (that: BigInt): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_>> (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Returns this wire statically right shifted by the specified amount,
-    * inserting zeros into the most significant bits.
+  /** Static right shift operator
     *
-    * The width of the output is the same as the input.
+    * @param that an amount to shift by
+    * @return this $coll with `that` many least significant bits truncated
+    * $unchangedWidth
+    * @group Bitwise
     */
   final def >> (that: Int): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_>> (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Returns this wire dynamically right shifted by the specified amount,
-    * inserting zeros into the most significant bits.
+  /** Dynamic right shift operator
     *
-    * The width of the output is the same as the input.
+    * @param that a hardware component
+    * @return this $coll dynamically shifted right by the value of `that` component, inserting zeros into the most
+    * significant bits.
+    * $unchangedWidth
+    * @group Bitwise
     */
   final def >> (that: UInt): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_>> (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-  /** Returns the contents of this wire as a [[Vec]] of [[Bool]]s.
-    */
+  /** Returns the contents of this wire as a [[scala.collection.Seq]] of [[Bool]]. */
   final def toBools(): Seq[Bool] = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def toBools(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Seq[Bool] =
     Seq.tabulate(this.getWidth)(i => this(i))
 
-  /** Reinterpret cast to a SInt.
+  /** Reinterpret this $coll as a [[SInt]]
     *
-    * @note value not guaranteed to be preserved: for example, an UInt of width
-    * 3 and value 7 (0b111) would become a SInt with value -1
+    * @note The value is not guaranteed to be preserved. For example, a [[UInt]] of width 3 and value 7 (0b111) would
+    * become a [[SInt]] with value -1.
     */
   final def asSInt(): SInt = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asSInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt
 
-  /** Reinterpret cast as a FixedPoint.
+  /** Reinterpret this $coll as a [[FixedPoint]].
     *
-    * @note value not guaranteed to be preserved: for example, an UInt of width
-    * 3 and value 7 (0b111) would become a FixedInt with value -1, the interpretation
-    * of the number is also affected by the specified binary point.  Caution advised
+    * @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
+    * point. '''Caution is advised!'''
     */
   final def asFixedPoint(that: BinaryPoint): FixedPoint = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asFixedPoint(that: BinaryPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = {
     throwException(s"Cannot call .asFixedPoint on $this")
   }
@@ -337,13 +419,16 @@ sealed abstract class Bits(width: Width)
     }
   }
 
-  /** Returns this wire concatenated with `other`, where this wire forms the
-    * most significant part and `other` forms the least significant part.
+  /** Concatenation operator
     *
-    * The width of the output is sum of the inputs.
+    * @param that a hardware component
+    * @return this $coll concatenated to the most significant end of `that`
+    * $sumWidth
+    * @group Bitwise
     */
   final def ## (that: Bits): UInt = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_## (that: Bits)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     val w = this.width + that.width
     pushOp(DefPrim(sourceInfo, UInt(w), ConcatOp, this.ref, that.ref))
@@ -360,8 +445,22 @@ sealed abstract class Bits(width: Width)
 }
 
 // REVIEW TODO: Further discussion needed on what Num actually is.
-/** Abstract trait defining operations available on numeric-like wire data
-  * types.
+/** Abstract trait defining operations available on numeric-like hardware data types.
+  *
+  * @tparam T the underlying type of the number
+  * @groupdesc Arithmetic Arithmetic hardware operators
+  * @groupdesc Comparison Comparison hardware operators
+  * @groupdesc Logical Logical hardware operators
+  * @define coll numeric-like type
+  * @define numType hardware type
+  * @define canHaveHighCost can result in significant cycle time and area costs
+  * @define canGenerateA This method can generate a
+  * @define singleCycleMul  @note $canGenerateA single-cycle multiplier which $canHaveHighCost.
+  * @define singleCycleDiv  @note $canGenerateA single-cycle divider which $canHaveHighCost.
+  * @define maxWidth        @note The width of the returned $numType is `max(width of this, width of that)`.
+  * @define maxWidthPlusOne @note The width of the returned $numType is `max(width of this, width of that) + 1`.
+  * @define sumWidth        @note The width of the returned $numType is `width of this` + `width of that`.
+  * @define unchangedWidth  @note The width of the returned $numType is unchanged, i.e., the `width of this`.
   */
 abstract trait Num[T <: Data] {
   self: Num[T] =>
@@ -371,89 +470,157 @@ abstract trait Num[T <: Data] {
 
   // REVIEW TODO: double check ops conventions against FIRRTL
 
-  /** Outputs the sum of `this` and `b`. The resulting width is the max of the
-    * operands plus 1 (should not overflow).
+  /** Addition operator
+    *
+    * @param that a $numType
+    * @return the sum of this $coll and `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
     */
   final def + (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_+ (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
-  /** Outputs the product of `this` and `b`. The resulting width is the sum of
-    * the operands.
+  /** Multiplication operator
     *
-    * @note can generate a single-cycle multiplier, which can result in
-    * significant cycle time and area costs
+    * @param that a $numType
+    * @return the product of this $coll and `that`
+    * $sumWidth
+    * $singleCycleMul
+    * @group Arithmetic
     */
   final def * (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_* (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
-  /** Outputs the quotient of `this` and `b`.
+  /** Division operator
     *
-    * TODO: full rules
+    * @param that a $numType
+    * @return the quotient of this $coll divided by `that`
+    * $singleCycleDiv
+    * @todo full rules
+    * @group Arithmetic
     */
   final def / (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_/ (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
+  /** Modulo operator
+    *
+    * @param that a $numType
+    * @return the remainder of this $coll divided by `that`
+    * $singleCycleDiv
+    * @group Arithmetic
+    */
   final def % (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_% (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
-  /** Outputs the difference of `this` and `b`. The resulting width is the max
-   *  of the operands plus 1 (should not overflow).
+  /** Subtraction operator
+    *
+    * @param that a $numType
+    * @return the difference of this $coll less `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
     */
   final def - (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_- (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
-  /** Outputs true if `this` < `b`.
+  /** Less than operator
+    *
+    * @param that a $numType
+    * @return a hardware [[Bool]] asserted if this $coll is less than `that`
+    * @group Comparison
     */
   final def < (that: T): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_< (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 
-  /** Outputs true if `this` <= `b`.
+  /** Less than or equal to operator
+    *
+    * @param that a $numType
+    * @return a hardware [[Bool]] asserted if this $coll is less than or equal to `that`
+    * @group Comparison
     */
   final def <= (that: T): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_<= (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 
-  /** Outputs true if `this` > `b`.
+  /** Greater than operator
+    *
+    * @param that a hardware component
+    * @return a hardware [[Bool]] asserted if this $coll is greater than `that`
+    * @group Comparison
     */
   final def > (that: T): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_> (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 
-  /** Outputs true if `this` >= `b`.
+  /** Greater than or equal to operator
+    *
+    * @param that a hardware component
+    * @return a hardware [[Bool]] asserted if this $coll is greather than or equal to `that`
+    * @group Comparison
     */
   final def >= (that: T): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_>= (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 
-  /** Outputs the absolute value of `this`. The resulting width is the unchanged */
+  /** Absolute value operator
+    *
+    * @return a $numType with a value equal to the absolute value of this $coll
+    * $unchangedWidth
+    * @group Arithmetic
+    */
   final def abs(): T = macro SourceInfoTransform.noArg
+
+  /** @group SourceInfoTransformMacro */
   def do_abs(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
-  /** Outputs the minimum of `this` and `b`. The resulting width is the max of
-    * the operands.
+  /** Minimum operator
+    *
+    * @param that a hardware $coll
+    * @return a $numType with a value equal to the mimimum value of this $coll and `that`
+    * $maxWidth
+    * @group Arithmetic
     */
   final def min(that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_min(that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
     Mux(this < that, this.asInstanceOf[T], that)
 
-  /** Outputs the maximum of `this` and `b`. The resulting width is the max of
-    * the operands.
+  /** Maximum operator
+    *
+    * @param that a $numType
+    * @return a $numType with a value equal to the mimimum value of this $coll and `that`
+    * $maxWidth
+    * @group Arithmetic
     */
   final def max(that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_max(that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
     Mux(this < that, that, this.asInstanceOf[T])
 }
 
-/** A data type for unsigned integers, represented as a binary bitvector.
-  * Defines arithmetic operations between other integer types.
+/** A data type for unsigned integers, represented as a binary bitvector. Defines arithmetic operations between other
+  * integer types.
+  *
+  * @define coll [[UInt]]
+  * @define numType $coll
+  * @define expandingWidth @note The width of the returned $coll is `width of this` + `1`.
+  * @define constantWidth  @note The width of the returned $coll is unchanged, i.e., `width of this`.
   */
 sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt] {
 
@@ -464,10 +631,25 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
     new UInt(w).asInstanceOf[this.type]
 
   // TODO: refactor to share documentation with Num or add independent scaladoc
+  /** Unary negation (expanding width)
+    *
+    * @return a $coll equal to zero minus this $coll
+    * $expandingWidth
+    * @group Arithmetic
+    */
   final def unary_- (): UInt = macro SourceInfoTransform.noArg
+
+  /** Unary negation (constant width)
+    *
+    * @return a $coll equal to zero minus this $coll shifted right by one.
+    * $constantWidth
+    * @group Arithmetic
+    */
   final def unary_-% (): UInt = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_unary_- (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) : UInt = 0.U - this
+  /** @group SourceInfoTransformMacro */
   def do_unary_-% (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = 0.U -% this
 
   override def do_+ (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = this +% that
@@ -479,48 +661,138 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   override def do_* (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width + that.width), TimesOp, that)
 
+  /** Multiplication operator
+    *
+    * @param that a hardware [[SInt]]
+    * @return the product of this $coll and `that`
+    * $sumWidth
+    * $singleCycleMul
+    * @group Arithmetic
+    */
   final def * (that: SInt): SInt = macro SourceInfoTransform.thatArg
+  /** @group SourceInfoTransformMacro */
   def do_* (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt = that * this
 
+  /** Addition operator (expanding width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def +& (that: UInt): UInt = macro SourceInfoTransform.thatArg
+
+  /** Addition operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that`
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def +% (that: UInt): UInt = macro SourceInfoTransform.thatArg
+
+  /** Subtraction operator (increasing width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def -& (that: UInt): UInt = macro SourceInfoTransform.thatArg
+
+  /** Subtraction operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that`
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def -% (that: UInt): UInt = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_+& (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt((this.width max that.width) + 1), AddOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_+% (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     (this +& that).tail(1)
+  /** @group SourceInfoTransformMacro */
   def do_-& (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, SInt((this.width max that.width) + 1), SubOp, that).asUInt
+  /** @group SourceInfoTransformMacro */
   def do_-% (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     (this -& that).tail(1)
 
+  /** Bitwise and operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise and of  this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def & (that: UInt): UInt = macro SourceInfoTransform.thatArg
+
+  /** Bitwise or operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise or of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def | (that: UInt): UInt = macro SourceInfoTransform.thatArg
+
+  /** Bitwise exclusive or (xor) operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise xor of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def ^ (that: UInt): UInt = macro SourceInfoTransform.thatArg
 
-//  override def abs: UInt = macro SourceInfoTransform.noArg
+  //  override def abs: UInt = macro SourceInfoTransform.noArg
   def do_abs(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = this
 
+  /** @group SourceInfoTransformMacro */
   def do_& (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width max that.width), BitAndOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_| (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width max that.width), BitOrOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_^ (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width max that.width), BitXorOp, that)
 
-  /** Returns this wire bitwise-inverted. */
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     unop(sourceInfo, UInt(width = width), BitNotOp)
 
-  // REVIEW TODO: Can this be defined on Bits?
+  // REVIEW TODO: Can these be defined on Bits?
+  /** Or reduction operator
+    *
+    * @return a hardware [[Bool]] resulting from every bit of this $coll or'd together
+    * @group Bitwise
+    */
   final def orR(): Bool = macro SourceInfoTransform.noArg
+
+  /** And reduction operator
+    *
+    * @return a hardware [[Bool]] resulting from every bit of this $coll and'd together
+    * @group Bitwise
+    */
   final def andR(): Bool = macro SourceInfoTransform.noArg
+
+  /** Exclusive or (xor) reduction operator
+    *
+    * @return a hardware [[Bool]] resulting from every bit of this $coll xor'd together
+    * @group Bitwise
+    */
   final def xorR(): Bool = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_orR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= 0.U
+  /** @group SourceInfoTransformMacro */
   def do_andR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = ~this === 0.U
+  /** @group SourceInfoTransformMacro */
   def do_xorR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = redop(sourceInfo, XorReduceOp)
 
   override def do_< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, LessOp, that)
@@ -531,14 +803,36 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   @chiselRuntimeDeprecated
   @deprecated("Use '=/=', which avoids potential precedence problems", "chisel3")
   final def != (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= that
+
+  /** Dynamic not equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is not equal to `that`
+    * @group Comparison
+    */
   final def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
+
+  /** Dynamic equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is equal to `that`
+    * @group Comparison
+    */
   final def === (that: UInt): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_=/= (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_=== (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, EqualOp, that)
 
+  /** Unary not
+    *
+    * @return a hardware [[Bool]] asserted if the least significant bit of this $coll is zero
+    * @group Bitwise
+    */
   final def unary_! () : Bool = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_unary_! (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) : Bool = this === 0.U(1.W)
 
   override def do_<< (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
@@ -554,25 +848,33 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   override def do_>> (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width), DynamicShiftRightOp, that)
 
+  /** Conditionally set or clear a bit
+    *
+    * @param off a dynamic offset
+    * @param dat set if true, clear if false
+    * @return a hrdware $coll with bit `off` set or cleared based on the value of `dat`
+    * $unchangedWidth
+    */
   final def bitSet(off: UInt, dat: Bool): UInt = macro UIntTransform.bitset
 
+  /** @group SourceInfoTransformMacro */
   def do_bitSet(off: UInt, dat: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     val bit = 1.U(1.W) << off
     Mux(dat, this | bit, ~(~this | bit))
   }
 
-  /** Returns this UInt as a [[SInt]] with an additional zero in the MSB.
-    */
   // TODO: this eventually will be renamed as toSInt, once the existing toSInt
   // completes its deprecation phase.
+  /** Zero extend as [[SInt]]
+    *
+    * @return an [[SInt]] equal to this $coll with an additional zero in its most significant bit
+    * @note The width of the returned [[SInt]] is `width of this` + `1`.
+    */
   final def zext(): SInt = macro SourceInfoTransform.noArg
+  /** @group SourceInfoTransformMacro */
   def do_zext(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     pushOp(DefPrim(sourceInfo, SInt(width + 1), ConvertOp, ref))
 
-  /** Returns this UInt as a [[SInt]], without changing width or bit value. The
-    * SInt is not guaranteed to have the same value (for example, if the MSB is
-    * high, it will be interpreted as a negative value).
-    */
   override def do_asSInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     pushOp(DefPrim(sourceInfo, SInt(width), AsSIntOp, ref))
   override def do_asUInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = this
@@ -620,6 +922,14 @@ trait UIntFactory {
 object UInt extends UIntFactory
 object Bits extends UIntFactory
 
+/** A data type for signed integers, represented as a binary bitvector. Defines arithmetic operations between other
+  * integer types.
+  *
+  * @define coll [[SInt]]
+  * @define numType $coll
+  * @define expandingWidth @note The width of the returned $coll is `width of this` + `1`.
+  * @define constantWidth  @note The width of the returned $coll is unchanged, i.e., `width of this`.
+  */
 sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt] {
 
   private[core] override def typeEquivalent(that: Data): Boolean =
@@ -628,10 +938,25 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   private[core] override def cloneTypeWidth(w: Width): this.type =
     new SInt(w).asInstanceOf[this.type]
 
+  /** Unary negation (expanding width)
+    *
+    * @return a hardware $coll equal to zero minus this $coll
+    * $expandingWidth
+    * @group Arithmetic
+    */
   final def unary_- (): SInt = macro SourceInfoTransform.noArg
+
+  /** Unary negation (constant width)
+    *
+    * @return a hardware $coll equal to zero minus `this` shifted right by one
+    * $constantWidth
+    * @group Arithmetic
+    */
   final def unary_-% (): SInt = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def unary_- (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt = 0.S - this
+  /** @group SourceInfoTransformMacro */
   def unary_-% (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt = 0.S -% this
 
   /** add (default - no growth) operator */
@@ -647,43 +972,109 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   override def do_% (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, SInt(this.width), RemOp, that)
 
+  /** Multiplication operator
+    *
+    * @param that a hardware $coll
+    * @return the product of this $coll and `that`
+    * $sumWidth
+    * $singleCycleMul
+    * @group Arithmetic
+    */
   final def * (that: UInt): SInt = macro SourceInfoTransform.thatArg
+  /** @group SourceInfoTransformMacro */
   def do_* (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt = {
     val thatToSInt = that.zext()
     val result = binop(sourceInfo, SInt(this.width + thatToSInt.width), TimesOp, thatToSInt)
     result.tail(1).asSInt
   }
 
-  /** add (width +1) operator */
+  /** Addition operator (expanding width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def +& (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** add (no growth) operator */
+
+  /** Addition operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that` shifted right by one
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def +% (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** subtract (width +1) operator */
+
+  /** Subtraction operator (increasing width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def -& (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** subtract (no growth) operator */
+
+  /** Subtraction operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that` shifted right by one
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def -% (that: SInt): SInt = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_+& (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, SInt((this.width max that.width) + 1), AddOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_+% (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     (this +& that).tail(1).asSInt
+  /** @group SourceInfoTransformMacro */
   def do_-& (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, SInt((this.width max that.width) + 1), SubOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_-% (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     (this -& that).tail(1).asSInt
 
+  /** Bitwise and operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise and of  this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def & (that: SInt): SInt = macro SourceInfoTransform.thatArg
+
+  /** Bitwise or operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise or of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def | (that: SInt): SInt = macro SourceInfoTransform.thatArg
+
+  /** Bitwise exclusive or (xor) operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise xor of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def ^ (that: SInt): SInt = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_& (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, UInt(this.width max that.width), BitAndOp, that).asSInt
+  /** @group SourceInfoTransformMacro */
   def do_| (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, UInt(this.width max that.width), BitOrOp, that).asSInt
+  /** @group SourceInfoTransformMacro */
   def do_^ (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, UInt(this.width max that.width), BitXorOp, that).asSInt
 
-  /** Returns this wire bitwise-inverted. */
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     unop(sourceInfo, UInt(width = width), BitNotOp).asSInt
 
@@ -695,10 +1086,26 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   @chiselRuntimeDeprecated
   @deprecated("Use '=/=', which avoids potential precedence problems", "chisel3")
   final def != (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= that
+
+  /** Dynamic not equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is not equal to `that`
+    * @group Comparison
+    */
   final def =/= (that: SInt): Bool = macro SourceInfoTransform.thatArg
+
+  /** Dynamic equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is equal to `that`
+    * @group Comparison
+    */
   final def === (that: SInt): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_=/= (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_=== (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, EqualOp, that)
 
 //  final def abs(): UInt = macro SourceInfoTransform.noArg
@@ -767,6 +1174,9 @@ sealed trait Reset extends Element with ToBoolable
 // REVIEW TODO: Why does this extend UInt and not Bits? Does defining airth
 // operations on a Bool make sense?
 /** A data type for booleans, defined as a single bit indicating true or false.
+  *
+  * @define coll [[Bool]]
+  * @define numType $coll
   */
 sealed class Bool() extends UInt(1.W) with Reset {
   private[core] override def cloneTypeWidth(w: Width): this.type = {
@@ -774,46 +1184,85 @@ sealed class Bool() extends UInt(1.W) with Reset {
     new Bool().asInstanceOf[this.type]
   }
 
+  /** Convert to a [[scala.Option]] of [[scala.Boolean]] */
   def litToBooleanOption: Option[Boolean] = litOption.map {
     case intVal if intVal == 1 => true
     case intVal if intVal == 0 => false
     case intVal => throwException(s"Boolean with unexpected literal value $intVal")
   }
 
+  /** Convert to a [[scala.Boolean]] */
   def litToBoolean: Boolean = litToBooleanOption.get
 
   // REVIEW TODO: Why does this need to exist and have different conventions
   // than Bits?
+
+  /** Bitwise and operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise and of  this $coll and `that`
+    * @group Bitwise
+    */
   final def & (that: Bool): Bool = macro SourceInfoTransform.thatArg
+
+  /** Bitwise or operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise or of this $coll and `that`
+    * @group Bitwise
+    */
   final def | (that: Bool): Bool = macro SourceInfoTransform.thatArg
+
+  /** Bitwise exclusive or (xor) operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise xor of this $coll and `that`
+    * @group Bitwise
+    */
   final def ^ (that: Bool): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_& (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     binop(sourceInfo, Bool(), BitAndOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_| (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     binop(sourceInfo, Bool(), BitOrOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_^ (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     binop(sourceInfo, Bool(), BitXorOp, that)
 
-  /** Returns this wire bitwise-inverted. */
+  /** @group SourceInfoTransformMacro */
   override def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     unop(sourceInfo, Bool(), BitNotOp)
 
-  /** Outputs the logical OR of two Bools.
-   */
+  /** Logical or operator
+    *
+    * @param that a hardware $coll
+    * @return the lgocial or of this $coll and `that`
+    * @note this is equivalent to [[Bool.|]]
+    * @group Logical
+    */
   def || (that: Bool): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_|| (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this | that
 
-  /** Outputs the logical AND of two Bools.
-   */
+  /** Logical and operator
+    *
+    * @param that a hardware $coll
+    * @return the lgocial and of this $coll and `that`
+    * @note this is equivalent to [[Bool.&]]
+    * @group Logical
+    */
   def && (that: Bool): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_&& (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this & that
 
-  /** Reinterprets this Bool as a Clock.  */
+  /** Reinterprets this $coll as a clock */
   def asClock(): Clock = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asClock(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Clock = pushOp(DefPrim(sourceInfo, Clock(), AsClockOp, ref))
 }
 
@@ -835,17 +1284,19 @@ trait BoolFactory {
 object Bool extends BoolFactory
 
 //scalastyle:off number.of.methods
-/**
-  * A sealed class representing a fixed point number that has a bit width and a binary point
-  * The width and binary point may be inferred.
+/** A sealed class representing a fixed point number that has a bit width and a binary point The width and binary point
+  * may be inferred.
   *
   * IMPORTANT: The API provided here is experimental and may change in the future.
   *
   * @param width       bit width of the fixed point number
-  * @param binaryPoint the position of the binary point with respect to the right most bit of the width
-  *                    currently this should be positive but it is hoped to soon support negative points
-  *                    and thus use this field as a simple exponent
-  * @param lit
+  * @param binaryPoint the position of the binary point with respect to the right most bit of the width currently this
+  *                    should be positive but it is hoped to soon support negative points and thus use this field as a
+  *                    simple exponent
+  * @define coll [[FixedPoint]]
+  * @define numType $coll
+  * @define expandingWidth @note The width of the returned $coll is `width of this` + `1`.
+  * @define constantWidth  @note The width of the returned $coll is unchanged, i.e., `width of this`.
   */
 sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
     extends Bits(width) with Num[FixedPoint] {
@@ -862,17 +1313,35 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
     case _ => this badConnect that
   }
 
+  /** Convert to a [[scala.Option]] of [[scala.Boolean]] */
   def litToDoubleOption: Option[Double] = litOption.map { intVal =>
     val multiplier = math.pow(2, binaryPoint.get)
     intVal.toDouble / multiplier
   }
 
+  /** Convert to a [[scala.Option]] */
   def litToDouble: Double = litToDoubleOption.get
 
+
+  /** Unary negation (expanding width)
+    *
+    * @return a hardware $coll equal to zero minus this $coll
+    * $expandingWidth
+    * @group Arithmetic
+    */
   final def unary_- (): FixedPoint = macro SourceInfoTransform.noArg
+
+  /** Unary negation (constant width)
+    *
+    * @return a hardware $coll equal to zero minus `this` shifted right by one
+    * $constantWidth
+    * @group Arithmetic
+    */
   final def unary_-% (): FixedPoint = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def unary_- (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = FixedPoint.fromBigInt(0) - this
+  /** @group SourceInfoTransformMacro */
   def unary_-% (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = FixedPoint.fromBigInt(0) -% this
 
   /** add (default - no growth) operator */
@@ -888,23 +1357,70 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   override def do_% (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     throwException(s"mod is illegal on FixedPoint types")
 
+
+  /** Multiplication operator
+    *
+    * @param that a hardware [[UInt]]
+    * @return the product of this $coll and `that`
+    * $sumWidth
+    * $singleCycleMul
+    * @group Arithmetic
+    */
   final def * (that: UInt): FixedPoint = macro SourceInfoTransform.thatArg
+  /** @group SourceInfoTransformMacro */
   def do_* (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     binop(sourceInfo, FixedPoint(this.width + that.width, binaryPoint), TimesOp, that)
 
+  /** Multiplication operator
+    *
+    * @param that a hardware [[SInt]]
+    * @return the product of this $coll and `that`
+    * $sumWidth
+    * $singleCycleMul
+    * @group Arithmetic
+    */
   final def * (that: SInt): FixedPoint = macro SourceInfoTransform.thatArg
+  /** @group SourceInfoTransformMacro */
   def do_* (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     binop(sourceInfo, FixedPoint(this.width + that.width, binaryPoint), TimesOp, that)
 
-  /** add (width +1) operator */
+  /** Addition operator (expanding width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def +& (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
-  /** add (no growth) operator */
+
+  /** Addition operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the sum of this $coll and `that` shifted right by one
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def +% (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
-  /** subtract (width +1) operator */
+
+  /** Subtraction operator (increasing width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that`
+    * $maxWidthPlusOne
+    * @group Arithmetic
+    */
   final def -& (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
-  /** subtract (no growth) operator */
+
+  /** Subtraction operator (constant width)
+    *
+    * @param that a hardware $coll
+    * @return the difference of this $coll less `that` shifted right by one
+    * $maxWidth
+    * @group Arithmetic
+    */
   final def -% (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_+& (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = {
     (this.width, that.width, this.binaryPoint, that.binaryPoint) match {
       case (KnownWidth(thisWidth), KnownWidth(thatWidth), KnownBinaryPoint(thisBP), KnownBinaryPoint(thatBP)) =>
@@ -919,8 +1435,10 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
     }
   }
 
+  /** @group SourceInfoTransformMacro */
   def do_+% (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     (this +& that).tail(1).asFixedPoint(this.binaryPoint max that.binaryPoint)
+  /** @group SourceInfoTransformMacro */
   def do_-& (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = {
     (this.width, that.width, this.binaryPoint, that.binaryPoint) match {
       case (KnownWidth(thisWidth), KnownWidth(thatWidth), KnownBinaryPoint(thisBP), KnownBinaryPoint(thatBP)) =>
@@ -935,22 +1453,50 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
     }
   }
 
+  /** @group SourceInfoTransformMacro */
   def do_-% (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     (this -& that).tail(1).asFixedPoint(this.binaryPoint max that.binaryPoint)
 
+  /** Bitwise and operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise and of  this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def & (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
+
+  /** Bitwise or operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise or of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def | (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
+
+  /** Bitwise exclusive or (xor) operator
+    *
+    * @param that a hardware $coll
+    * @return the bitwise xor of this $coll and `that`
+    * $maxWidth
+    * @group Bitwise
+    */
   final def ^ (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_& (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     throwException(s"And is illegal between $this and $that")
+  /** @group SourceInfoTransformMacro */
   def do_| (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     throwException(s"Or is illegal between $this and $that")
+  /** @group SourceInfoTransformMacro */
   def do_^ (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     throwException(s"Xor is illegal between $this and $that")
 
   final def setBinaryPoint(that: Int): FixedPoint = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_setBinaryPoint(that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = this.binaryPoint match {
     case KnownBinaryPoint(value) =>
       binop(sourceInfo, FixedPoint(this.width + (that - value), KnownBinaryPoint(that)), SetBinaryPoint, that)
@@ -958,7 +1504,7 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
       binop(sourceInfo, FixedPoint(UnknownWidth(), KnownBinaryPoint(that)), SetBinaryPoint, that)
   }
 
-  /** Returns this wire bitwise-inverted. */
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     throwException(s"Not is illegal on $this")
 
@@ -969,11 +1515,28 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   override def do_>= (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, GreaterEqOp, that)
 
   final def != (that: FixedPoint): Bool = macro SourceInfoTransform.thatArg
+
+  /** Dynamic not equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is not equal to `that`
+    * @group Comparison
+    */
   final def =/= (that: FixedPoint): Bool = macro SourceInfoTransform.thatArg
+
+  /** Dynamic equals operator
+    *
+    * @param that a hardware $coll
+    * @return a hardware [[Bool]] asserted if this $coll is equal to `that`
+    * @group Comparison
+    */
   final def === (that: FixedPoint): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_!= (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_=/= (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
+  /** @group SourceInfoTransformMacro */
   def do_=== (that: FixedPoint)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, EqualOp, that)
 
   def do_abs(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint = {
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 171a2bff..cab6075e 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -7,7 +7,8 @@ import scala.language.experimental.macros
 import chisel3.internal._
 import chisel3.internal.Builder.{pushCommand, pushOp}
 import chisel3.internal.firrtl._
-import chisel3.internal.sourceinfo._
+import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform, UnlocatableSourceInfo, DeprecatedSourceInfo}
+import chisel3.SourceInfoDoc
 import chisel3.core.BiConnect.DontCareCantBeSink
 
 /** User-specified directions.
@@ -197,8 +198,11 @@ object Flipped {
   * must be representable as some number (need not be known at Chisel compile
   * time) of bits, and must have methods to pack / unpack structured data to /
   * from bits.
+  *
+  * @groupdesc Connect Utilities for connecting hardware components
+  * @define coll data
   */
-abstract class Data extends HasId with NamedComponent {
+abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
   // This is a bad API that punches through object boundaries.
   @deprecated("pending removal once all instances replaced", "chisel3")
   private[chisel3] def flatten: IndexedSeq[Element] = {
@@ -381,7 +385,22 @@ abstract class Data extends HasId with NamedComponent {
     clone
   }
 
+  /** Connect this $coll to that $coll mono-directionally and element-wise.
+    *
+    * This uses the [[MonoConnect]] algorithm.
+    *
+    * @param that the $coll to connect to
+    * @group Connect
+    */
   final def := (that: Data)(implicit sourceInfo: SourceInfo, connectionCompileOptions: CompileOptions): Unit = this.connect(that)(sourceInfo, connectionCompileOptions)
+
+  /** Connect this $coll to that $coll bi-directionally and element-wise.
+    *
+    * This uses the [[BiConnect]] algorithm.
+    *
+    * @param that the $coll to connect to
+    * @group Connect
+    */
   final def <> (that: Data)(implicit sourceInfo: SourceInfo, connectionCompileOptions: CompileOptions): Unit = this.bulkConnect(that)(sourceInfo, connectionCompileOptions)
 
   @chiselRuntimeDeprecated
@@ -432,6 +451,7 @@ abstract class Data extends HasId with NamedComponent {
     */
   def asTypeOf[T <: Data](that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asTypeOf[T <: Data](that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     val thatCloned = Wire(that.cloneTypeFull)
     thatCloned.connectFromBits(this.asUInt())
@@ -452,6 +472,7 @@ abstract class Data extends HasId with NamedComponent {
     */
   final def asUInt(): UInt = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asUInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt
 
   /** Default pretty printing */
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Mem.scala b/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
index 73bf3708..09e30fec 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
@@ -8,6 +8,7 @@ import chisel3.internal._
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform, UnlocatableSourceInfo, MemTransform}
+import chisel3.SourceInfoDoc
 
 object Mem {
   @chiselRuntimeDeprecated
@@ -20,6 +21,8 @@ object Mem {
     * @param t data type of memory element
     */
   def apply[T <: Data](size: Int, t: T): Mem[T] = macro MemTransform.apply[T]
+
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: Data](size: Int, t: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Mem[T] = {
     if (compileOptions.declaredTypeMustBeUnbound) {
       requireIsChiselType(t, "memory type")
@@ -31,7 +34,7 @@ object Mem {
   }
 }
 
-sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId with NamedComponent {
+sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId with NamedComponent with SourceInfoDoc {
   // REVIEW TODO: make accessors (static/dynamic, read/write) combinations consistent.
 
   /** Creates a read accessor into the memory with static addressing. See the
@@ -39,6 +42,7 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId wi
     */
   def apply(x: Int): T = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   def do_apply(idx: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     require(idx >= 0 && idx < length)
     apply(idx.asUInt)
@@ -49,6 +53,7 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId wi
     */
   def apply(x: UInt): T = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   def do_apply(idx: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
     makePort(sourceInfo, idx, MemPortDirection.INFER)
 
@@ -57,6 +62,7 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId wi
     */
   def read(x: UInt): T = macro SourceInfoTransform.xArg
 
+  /** @group SourceInfoTransformMacro */
   def do_read(idx: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
     makePort(sourceInfo, idx, MemPortDirection.READ)
 
@@ -130,6 +136,7 @@ object SyncReadMem {
     */
   def apply[T <: Data](size: Int, t: T): SyncReadMem[T] = macro MemTransform.apply[T]
 
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: Data](size: Int, t: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SyncReadMem[T] = {
     if (compileOptions.declaredTypeMustBeUnbound) {
       requireIsChiselType(t, "memory type")
@@ -154,6 +161,7 @@ object SyncReadMem {
 sealed class SyncReadMem[T <: Data] private (t: T, n: Int) extends MemBase[T](t, n) {
   def read(x: UInt, en: Bool): T = macro SourceInfoTransform.xEnArg
 
+  /** @group SourceInfoTransformMacro */
   def do_read(addr: UInt, enable: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     val a = Wire(UInt())
     a := DontCare
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Module.scala b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
index 0cf05496..399f0462 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Module.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
@@ -12,10 +12,11 @@ import chisel3.internal._
 import chisel3.internal.Builder._
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{InstTransform, SourceInfo}
+import chisel3.SourceInfoDoc
 
 import _root_.firrtl.annotations.{CircuitName, ModuleName}
 
-object Module {
+object Module extends SourceInfoDoc {
   /** A wrapper method that all Module instantiations must be wrapped in
     * (necessary to help Chisel track internal state).
     *
@@ -25,6 +26,7 @@ object Module {
     */
   def apply[T <: BaseModule](bc: => T): T = macro InstTransform.apply[T]
 
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: BaseModule](bc: => T)
                                (implicit sourceInfo: SourceInfo,
                                          compileOptions: CompileOptions): T = {
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Mux.scala b/chiselFrontend/src/main/scala/chisel3/core/Mux.scala
index e4ef001f..56c145b5 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Mux.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Mux.scala
@@ -9,8 +9,9 @@ import chisel3.internal.Builder.{pushOp}
 import chisel3.internal.sourceinfo.{SourceInfo, MuxTransform}
 import chisel3.internal.firrtl._
 import chisel3.internal.firrtl.PrimOp._
+import chisel3.SourceInfoDoc
 
-object Mux {
+object Mux extends SourceInfoDoc {
   /** Creates a mux, whose output is one of the inputs depending on the
     * value of the condition.
     *
@@ -24,6 +25,7 @@ object Mux {
     */
   def apply[T <: Data](cond: Bool, con: T, alt: T): T = macro MuxTransform.apply[T]
 
+  /** @group SourceInfoTransformMacro */
   def do_apply[T <: Data](cond: Bool, con: T, alt: T)(implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): T = {
     requireIsHardware(cond, "mux condition")
diff --git a/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala b/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
index 69f54102..e87fb045 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
@@ -18,6 +18,7 @@ private[chisel3] object SeqUtils {
     */
   def asUInt[T <: Bits](in: Seq[T]): UInt = macro SourceInfoTransform.inArg
 
+  /** @group SourceInfoTransformMacros */
   def do_asUInt[T <: Bits](in: Seq[T])(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = {
     if (in.tail.isEmpty) {
       in.head.asUInt
@@ -32,6 +33,7 @@ private[chisel3] object SeqUtils {
     */
   def count(in: Seq[Bool]): UInt = macro SourceInfoTransform.inArg
 
+  /** @group SourceInfoTransformMacros */
   def do_count(in: Seq[Bool])(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt = in.size match {
     case 0 => 0.U
     case 1 => in.head
@@ -42,6 +44,7 @@ private[chisel3] object SeqUtils {
     */
   def priorityMux[T <: Data](in: Seq[(Bool, T)]): T = macro SourceInfoTransform.inArg
 
+  /** @group SourceInfoTransformMacros */
   def do_priorityMux[T <: Data](in: Seq[(Bool, T)])
                                (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     if (in.size == 1) {
@@ -60,6 +63,7 @@ private[chisel3] object SeqUtils {
   def oneHotMux[T <: Data](in: Iterable[(Bool, T)]): T = macro SourceInfoTransform.inArg
 
   //scalastyle:off method.length cyclomatic.complexity
+  /** @group SourceInfoTransformMacros */
   def do_oneHotMux[T <: Data](in: Iterable[(Bool, T)])
                              (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     if (in.tail.isEmpty) {
diff --git a/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala
new file mode 100644
index 00000000..ad320d5d
--- /dev/null
+++ b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala
@@ -0,0 +1,42 @@
+// See LICENSE for license details
+
+package chisel3
+
+/** Provides ScalaDoc information for "hidden" `do_*` methods
+  *
+  * Mix this into classes/objects that have `do_*` methods to get access to the shared `SourceInfoTransformMacro`
+  * ScalaDoc group and the lengthy `groupdesc` below.
+  *
+  * @groupdesc SourceInfoTransformMacro
+  *
+  * <p>
+  *   '''These internal methods are not part of the public-facing API!'''
+  *   <br>
+  *   <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 `toBools` 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>
+  *
+  *   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
+  */
+trait SourceInfoDoc
diff --git a/src/main/scala/chisel3/compatibility.scala b/src/main/scala/chisel3/compatibility.scala
index 0212aca9..1d0c0ff7 100644
--- a/src/main/scala/chisel3/compatibility.scala
+++ b/src/main/scala/chisel3/compatibility.scala
@@ -120,15 +120,18 @@ package object Chisel {     // scalastyle:ignore package.object.name
       apply(Seq.fill(n)(gen))
 
     def apply[T <: Data](elts: Seq[T]): Vec[T] = macro VecTransform.apply_elts
+    /** @group SourceInfoTransformMacro */
     def do_apply[T <: Data](elts: Seq[T])(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] =
       chisel3.core.VecInit(elts)
 
     def apply[T <: Data](elt0: T, elts: T*): Vec[T] = macro VecTransform.apply_elt0
+    /** @group SourceInfoTransformMacro */
     def do_apply[T <: Data](elt0: T, elts: T*)
         (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] =
       chisel3.core.VecInit(elt0 +: elts.toSeq)
 
     def tabulate[T <: Data](n: Int)(gen: (Int) => T): Vec[T] = macro VecTransform.tabulate
+    /** @group SourceInfoTransformMacro */
     def do_tabulate[T <: Data](n: Int)(gen: (Int) => T)
         (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] =
       chisel3.core.VecInit.tabulate(n)(gen)
diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala
index 7f1ad040..b7c39bad 100644
--- a/src/main/scala/chisel3/package.scala
+++ b/src/main/scala/chisel3/package.scala
@@ -50,11 +50,11 @@ package object chisel3 {    // scalastyle:ignore package.object.name
     @chiselRuntimeDeprecated
     @deprecated("Input(Data) should be used over Data.asInput", "chisel3")
     def asInput: T = Input(target)
-    
+
     @chiselRuntimeDeprecated
     @deprecated("Output(Data) should be used over Data.asOutput", "chisel3")
     def asOutput: T = Output(target)
-    
+
     @chiselRuntimeDeprecated
     @deprecated("Flipped(Data) should be used over Data.flip", "chisel3")
     def flip(): T = Flipped(target)
@@ -152,7 +152,7 @@ package object chisel3 {    // scalastyle:ignore package.object.name
     @chiselRuntimeDeprecated
     @deprecated("use n.U", "chisel3, will be removed by end of 2017")
     def apply(n: String): UInt = n.asUInt
-    
+
     /** Create a UInt literal with fixed width. */
     @chiselRuntimeDeprecated
     @deprecated("use n.U(width.W)", "chisel3, will be removed by end of 2017")
@@ -192,7 +192,7 @@ package object chisel3 {    // scalastyle:ignore package.object.name
     @chiselRuntimeDeprecated
     @deprecated("use SInt(width.W)", "chisel3, will be removed by end of 2017")
     def width(width: Int): SInt = apply(width.W)
-    
+
     /** Create an SInt type with specified width. */
     @chiselRuntimeDeprecated
     @deprecated("use SInt(width)", "chisel3, will be removed by end of 2017")
@@ -202,7 +202,7 @@ package object chisel3 {    // scalastyle:ignore package.object.name
     @chiselRuntimeDeprecated
     @deprecated("use value.S", "chisel3, will be removed by end of 2017")
     def apply(value: BigInt): SInt = value.asSInt
-    
+
     /** Create an SInt literal with fixed width. */
     @chiselRuntimeDeprecated
     @deprecated("use value.S(width.W)", "chisel3, will be removed by end of 2017")
@@ -257,7 +257,7 @@ package object chisel3 {    // scalastyle:ignore package.object.name
   val SeqMem = chisel3.core.SyncReadMem
   @deprecated("Use 'SyncReadMem'", "chisel3")
   type SeqMem[T <: Data] = chisel3.core.SyncReadMem[T]
-  
+
   val Module = chisel3.core.Module
   type Module = chisel3.core.LegacyModule
 
@@ -367,18 +367,20 @@ package object chisel3 {    // scalastyle:ignore package.object.name
   implicit class fromIntToWidth(x: Int) extends chisel3.core.fromIntToWidth(x)
   implicit class fromIntToBinaryPoint(x: Int) extends chisel3.core.fromIntToBinaryPoint(x)
 
-  implicit class fromUIntToBitPatComparable(x: UInt) {
+  implicit class fromUIntToBitPatComparable(x: UInt) extends chisel3.SourceInfoDoc {
     import scala.language.experimental.macros
     import internal.sourceinfo.{SourceInfo, SourceInfoTransform}
 
     final def === (that: BitPat): Bool = macro SourceInfoTransform.thatArg
     final def =/= (that: BitPat): Bool = macro SourceInfoTransform.thatArg
 
+    /** @group SourceInfoTransformMacro */
     def do_=== (that: BitPat)  // scalastyle:ignore method.name
         (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = that === x
+    /** @group SourceInfoTransformMacro */
     def do_=/= (that: BitPat)  // scalastyle:ignore method.name
         (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = that =/= x
-        
+
     final def != (that: BitPat): Bool = macro SourceInfoTransform.thatArg
     @chiselRuntimeDeprecated
     @deprecated("Use '=/=', which avoids potential precedence problems", "chisel3")
diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
index 6ff08bea..6cba497e 100644
--- a/src/main/scala/chisel3/util/BitPat.scala
+++ b/src/main/scala/chisel3/util/BitPat.scala
@@ -88,15 +88,17 @@ object BitPat {
   * "b10001".U === BitPat("b101??") // evaluates to false.B
   * }}}
   */
-sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) {
+sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) extends SourceInfoDoc {
   def getWidth: Int = width
   def === (that: UInt): Bool = macro SourceInfoTransform.thatArg
   def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_=== (that: UInt)  // scalastyle:ignore method.name
       (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     value.asUInt === (that & mask.asUInt)
   }
+  /** @group SourceInfoTransformMacro */
   def do_=/= (that: UInt)  // scalastyle:ignore method.name
       (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     !(this === that)