From 66a59036eae0c9d75055f09df6696bd8431d9c59 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:42:16 -0400
Subject: Add Connect ScalaDoc group to Data

This adds the ScalaDoc group "Connect" to the Data class.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Data.scala | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 171a2bff..151bc13f 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.util.SourceInfoDoc
 import chisel3.core.BiConnect.DontCareCantBeSink
 
 /** User-specified directions.
@@ -197,6 +198,8 @@ 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
   */
 abstract class Data extends HasId with NamedComponent {
   // This is a bad API that punches through object boundaries.
-- 
cgit v1.2.3


From c5b2210620bb701b8d82a121950dbf8e496243c0 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:31:23 -0400
Subject: Add Bitwise ScalaDoc group to Bits

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 10b6ec8e..57c0e240 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -59,6 +59,8 @@ private[chisel3] sealed trait ToBoolable extends Element {
 
 /** A data type for values represented by a single bitvector. Provides basic
   * bitwise operations.
+  *
+  * @groupdesc Bitwise Bitwise hardware operators
   */
 //scalastyle:off number.of.methods
 sealed abstract class Bits(width: Width)
-- 
cgit v1.2.3


From 6226781ac170988d8e4b71974edf88fbe52aed62 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:52:56 -0400
Subject: Add Arithmetic ScalaDoc group to Num

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 57c0e240..f70d5f53 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -364,6 +364,8 @@ 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.
+  *
+  * @groupdesc Arithmetic Arithmetic hardware operators
   */
 abstract trait Num[T <: Data] {
   self: Num[T] =>
-- 
cgit v1.2.3


From d03e5a190048e6d6043420d7480c023b8f5e886f Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:53:10 -0400
Subject: Add Comparison ScalaDoc group to Num

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 1 +
 1 file changed, 1 insertion(+)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index f70d5f53..e8223e19 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -366,6 +366,7 @@ sealed abstract class Bits(width: Width)
   * types.
   *
   * @groupdesc Arithmetic Arithmetic hardware operators
+  * @groupdesc Comparison Comparison hardware operators
   */
 abstract trait Num[T <: Data] {
   self: Num[T] =>
-- 
cgit v1.2.3


From 34a650e6f5127ebe11c8ce3ef434ee16c6b25bf9 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:47:29 -0400
Subject: Add Logical ScalaDoc group to Num

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 1 +
 1 file changed, 1 insertion(+)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index e8223e19..476764ee 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -367,6 +367,7 @@ sealed abstract class Bits(width: Width)
   *
   * @groupdesc Arithmetic Arithmetic hardware operators
   * @groupdesc Comparison Comparison hardware operators
+  * @groupdesc Logical Logical hardware operators
   */
 abstract trait Num[T <: Data] {
   self: Num[T] =>
-- 
cgit v1.2.3


From 57e8774c34fc28dd34cdec5e8a1bf82f3cd4e0cd Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:39:28 -0400
Subject: Put do_* methods in SourceInfoTransformMacro group

This places all do_* methods (and two unary methods in SInt and FixedPoint
that act like do_* methods) inside the ScalaDoc group
"SourceInfoTransformMacro". Classes/objects which need information about
this group have an additional bare trait mixed in, `SourceInfoDoc`, that
provides information about the group and its priority.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Aggregate.scala    |  19 +++-
 .../src/main/scala/chisel3/core/Bits.scala         | 113 +++++++++++++++++++--
 .../src/main/scala/chisel3/core/Data.scala         |   6 +-
 .../src/main/scala/chisel3/core/Mem.scala          |  10 +-
 .../src/main/scala/chisel3/core/Module.scala       |   4 +-
 .../src/main/scala/chisel3/core/Mux.scala          |   4 +-
 .../src/main/scala/chisel3/core/SeqUtils.scala     |   4 +
 7 files changed, 141 insertions(+), 19 deletions(-)

(limited to 'chiselFrontend')

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 476764ee..053c20f2 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -54,6 +54,7 @@ private[chisel3] sealed trait ToBoolable extends Element {
     */
   final def toBool(): Bool = macro SourceInfoWhiteboxTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_toBool(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool
 }
 
@@ -104,6 +105,7 @@ sealed abstract class Bits(width: Width)
   final def tail(n: Int): UInt = macro SourceInfoTransform.nArg
   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) =>
@@ -114,7 +116,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")
@@ -128,6 +130,7 @@ sealed abstract class Bits(width: Width)
     */
   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)")
@@ -149,6 +152,7 @@ sealed abstract class Bits(width: Width)
     */
   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
@@ -156,6 +160,7 @@ sealed abstract class Bits(width: Width)
     */
   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)
@@ -172,6 +177,7 @@ sealed abstract class Bits(width: Width)
     */
   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)")
@@ -190,6 +196,7 @@ sealed abstract class Bits(width: Width)
   // REVIEW TODO: again, is this necessary? Or just have this and use implicits?
   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)
 
@@ -222,6 +229,7 @@ sealed abstract class Bits(width: Width)
     */
   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)
@@ -230,14 +238,15 @@ sealed abstract class Bits(width: Width)
   /** Returns this wire bitwise-inverted. */
   final def unary_~ (): Bits = macro SourceInfoWhiteboxTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
-
   /** Shift left operation */
   // 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,
@@ -247,6 +256,7 @@ sealed abstract class Bits(width: Width)
     */
   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,
@@ -256,12 +266,14 @@ sealed abstract class Bits(width: Width)
     */
   final def << (that: UInt): Bits = macro SourceInfoWhiteboxTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_<< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits
 
   /** Shift right operation */
   // 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,
@@ -271,6 +283,7 @@ sealed abstract class Bits(width: Width)
     */
   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,
@@ -280,6 +293,7 @@ sealed abstract class Bits(width: Width)
     */
   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.
@@ -296,6 +310,7 @@ sealed abstract class Bits(width: Width)
     */
   final def asSInt(): SInt = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asSInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt
 
   /** Reinterpret cast as a FixedPoint.
@@ -306,6 +321,7 @@ sealed abstract class Bits(width: Width)
     */
   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")
   }
@@ -346,6 +362,7 @@ sealed abstract class Bits(width: Width)
     */
   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))
@@ -382,6 +399,7 @@ abstract trait Num[T <: Data] {
     */
   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
@@ -392,6 +410,7 @@ abstract trait Num[T <: Data] {
     */
   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`.
@@ -400,10 +419,12 @@ abstract trait Num[T <: Data] {
     */
   final def / (that: T): T = macro SourceInfoTransform.thatArg
 
+  /** @group SourceInfoTransformMacro */
   def do_/ (that: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T
 
   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
@@ -411,34 +432,41 @@ abstract trait Num[T <: Data] {
     */
   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`.
     */
   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`.
     */
   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`.
     */
   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`.
     */
   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 */
   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
@@ -446,6 +474,7 @@ abstract trait Num[T <: Data] {
     */
   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)
 
@@ -454,6 +483,7 @@ abstract trait Num[T <: Data] {
     */
   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])
 }
@@ -473,7 +503,9 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   final def unary_- (): UInt = macro SourceInfoTransform.noArg
   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
@@ -486,6 +518,7 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
     binop(sourceInfo, UInt(this.width + that.width), TimesOp, that)
 
   final def * (that: SInt): SInt = macro SourceInfoTransform.thatArg
+  /** @group SourceInfoTransformMacro */
   def do_* (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt = that * this
 
   final def +& (that: UInt): UInt = macro SourceInfoTransform.thatArg
@@ -493,12 +526,16 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   final def -& (that: UInt): UInt = macro SourceInfoTransform.thatArg
   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)
 
@@ -506,17 +543,22 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   final def | (that: UInt): UInt = macro SourceInfoTransform.thatArg
   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. */
+  /** Returns this wire bitwise-inverted.
+    * @group SourceInfoTransformMacro
+    */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     unop(sourceInfo, UInt(width = width), BitNotOp)
 
@@ -525,8 +567,11 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   final def andR(): Bool = macro SourceInfoTransform.noArg
   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)
@@ -540,11 +585,14 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   final def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
   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)
 
   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 =
@@ -562,6 +610,7 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
 
   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))
@@ -572,6 +621,7 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   // TODO: this eventually will be renamed as toSInt, once the existing toSInt
   // completes its deprecation phase.
   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))
 
@@ -637,7 +687,9 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   final def unary_- (): SInt = macro SourceInfoTransform.noArg
   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 */
@@ -654,27 +706,36 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
     binop(sourceInfo, SInt(this.width), RemOp, that)
 
   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 */
+  /** add (width +1) operator
+    */
   final def +& (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** add (no growth) operator */
+  /** add (no growth) operator
+    */
   final def +% (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** subtract (width +1) operator */
+  /** subtract (width +1) operator
+    */
   final def -& (that: SInt): SInt = macro SourceInfoTransform.thatArg
-  /** subtract (no growth) operator */
+  /** subtract (no growth) operator
+    */
   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
 
@@ -682,14 +743,19 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   final def | (that: SInt): SInt = macro SourceInfoTransform.thatArg
   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. */
+  /** Returns this wire bitwise-inverted.
+    * @group SourceInfoTransformMacro
+    */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     unop(sourceInfo, UInt(width = width), BitNotOp).asSInt
 
@@ -704,7 +770,9 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   final def =/= (that: SInt): Bool = macro SourceInfoTransform.thatArg
   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
@@ -794,32 +862,40 @@ sealed class Bool() extends UInt(1.W) with Reset {
   final def | (that: Bool): Bool = macro SourceInfoTransform.thatArg
   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. */
+  /** 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.
-   */
+    */
   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.
    */
   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.  */
   def asClock(): Clock = macro SourceInfoTransform.noArg
 
+  /** @group SourceInfoTransformMacro */
   def do_asClock(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Clock = pushOp(DefPrim(sourceInfo, Clock(), AsClockOp, ref))
 }
 
@@ -878,7 +954,9 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   final def unary_- (): FixedPoint = macro SourceInfoTransform.noArg
   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 */
@@ -895,10 +973,12 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
     throwException(s"mod is illegal on FixedPoint types")
 
   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)
 
   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)
 
@@ -911,6 +991,7 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   /** subtract (no growth) operator */
   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)) =>
@@ -925,8 +1006,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)) =>
@@ -941,6 +1024,7 @@ 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)
 
@@ -948,15 +1032,19 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   final def | (that: FixedPoint): FixedPoint = macro SourceInfoTransform.thatArg
   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)
@@ -978,8 +1066,11 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   final def =/= (that: FixedPoint): Bool = macro SourceInfoTransform.thatArg
   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 151bc13f..04209cef 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -8,7 +8,7 @@ import chisel3.internal._
 import chisel3.internal.Builder.{pushCommand, pushOp}
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform, UnlocatableSourceInfo, DeprecatedSourceInfo}
-import chisel3.util.SourceInfoDoc
+import chisel3.SourceInfoDoc
 import chisel3.core.BiConnect.DontCareCantBeSink
 
 /** User-specified directions.
@@ -201,7 +201,7 @@ object Flipped {
   *
   * @groupdesc Connect Utilities for connecting hardware components
   */
-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] = {
@@ -435,6 +435,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())
@@ -455,6 +456,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) {
-- 
cgit v1.2.3


From fefdc9441d248bf3d72e7e7e200a0caa63607049 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:43:37 -0400
Subject: Put := and <> methods in Connect ScalaDoc group

This puts Data's connection methods, `:=` and `<>`, in the ScalaDoc
`Connect` group. These groups will propagate through to all children of
Data, e.g., UInt, and cause those methods to be grouped in the ScalaDoc of
these children.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Data.scala | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 04209cef..cab6075e 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -200,6 +200,7 @@ object Flipped {
   * from bits.
   *
   * @groupdesc Connect Utilities for connecting hardware components
+  * @define coll data
   */
 abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
   // This is a bad API that punches through object boundaries.
@@ -384,7 +385,22 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
     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
-- 
cgit v1.2.3


From d69109af8265a3d51dd8a043544e250f1d17d202 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:31:46 -0400
Subject: Add Bits ScalaDoc documentation

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 149 +++++++++++++++------
 1 file changed, 106 insertions(+), 43 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 053c20f2..b813fa6f 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -58,14 +58,15 @@ private[chisel3] sealed trait ToBoolable extends Element {
   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
@@ -102,7 +103,20 @@ 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 */
@@ -125,8 +139,10 @@ 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
 
@@ -145,18 +161,21 @@ 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
 
@@ -166,14 +185,16 @@ sealed abstract class Bits(width: Width)
     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
 
@@ -194,6 +215,17 @@ 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 */
@@ -223,9 +255,13 @@ 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
 
@@ -235,13 +271,23 @@ sealed abstract class Bits(width: Width)
     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
@@ -249,75 +295,90 @@ sealed abstract class Bits(width: Width)
   /** @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
 
@@ -355,10 +416,12 @@ 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
 
-- 
cgit v1.2.3


From 981df2bdff248597095e247907444395c9b5a2b4 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Mon, 13 Aug 2018 20:58:52 -0400
Subject: Add Num ScalaDoc documentation

This includes general documentation for the arithmetic and comparison
operators of Num.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 108 ++++++++++++++++-----
 1 file changed, 85 insertions(+), 23 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index b813fa6f..032a7ed7 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -442,12 +442,22 @@ sealed abstract class Bits(width: Width) extends Element(width) with ToBoolable
 }
 
 // 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] =>
@@ -457,83 +467,129 @@ 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
 
@@ -541,8 +597,12 @@ abstract trait Num[T <: Data] {
   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
 
@@ -551,8 +611,10 @@ abstract trait Num[T <: Data] {
     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]]
   */
 sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt] {
 
-- 
cgit v1.2.3


From d9cfbc485fce17a6303e57939a46a1b3dc43aace Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Mon, 13 Aug 2018 23:32:15 -0400
Subject: Add UInt ScalaDoc documentation

This adds documentation of Arithmetic, Comparison, and Bitwise operator
methods of UInt.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 138 +++++++++++++++++++--
 1 file changed, 128 insertions(+), 10 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 032a7ed7..76823235 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -615,6 +615,9 @@ abstract trait Num[T <: Data] {
   * 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] {
 
@@ -625,7 +628,20 @@ 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 */
@@ -642,13 +658,52 @@ 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 */
@@ -664,8 +719,31 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   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
@@ -681,15 +759,30 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   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
-    */
+  /** @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 */
@@ -707,7 +800,21 @@ 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 */
@@ -715,6 +822,11 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
   /** @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 */
@@ -733,6 +845,13 @@ 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 */
@@ -741,19 +860,18 @@ sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt
     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
-- 
cgit v1.2.3


From 55f411af086ce7046abc93ef039f32894631ce24 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Mon, 13 Aug 2018 23:54:18 -0400
Subject: Add SInt ScalaDoc documentation

Adds documentation of Arithmetic, Bitwise, and Comparison operators for
SInt.

The duplication of documentation between UInt and SInt strongly indicate a
unification around Num would make sense.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 101 +++++++++++++++++++--
 1 file changed, 94 insertions(+), 7 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 76823235..d6c7e65b 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -919,6 +919,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 =
@@ -927,7 +935,20 @@ 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 */
@@ -948,6 +969,14 @@ 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 = {
@@ -956,16 +985,39 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
     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
 
@@ -982,8 +1034,31 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   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 */
@@ -996,9 +1071,7 @@ sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt
   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
-    */
+  /** @group SourceInfoTransformMacro */
   def do_unary_~ (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     unop(sourceInfo, UInt(width = width), BitNotOp).asSInt
 
@@ -1010,7 +1083,21 @@ 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 */
-- 
cgit v1.2.3


From d602ad96bcef90ca797c29cbb33b442406064e2e Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 11:48:15 -0400
Subject: Add Bool ScalaDoc documentation

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 48 ++++++++++++++++++----
 1 file changed, 41 insertions(+), 7 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index d6c7e65b..e9f56602 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -1171,6 +1171,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 = {
@@ -1178,18 +1181,41 @@ 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 */
@@ -1202,27 +1228,35 @@ sealed class Bool() extends UInt(1.W) with Reset {
   def do_^ (that: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool =
     binop(sourceInfo, Bool(), BitXorOp, that)
 
-  /** Returns this wire bitwise-inverted.
-    * @group SourceInfoTransformMacro
-    */
+  /** @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 */
-- 
cgit v1.2.3


From c600d0b1e68f994c48e1abb961c734c7ba36f720 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 00:16:31 -0400
Subject: Add FixedPoint ScalaDoc documentation

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 .../src/main/scala/chisel3/core/Bits.scala         | 123 +++++++++++++++++++--
 1 file changed, 111 insertions(+), 12 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index e9f56602..3e0ddc0a 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -1281,17 +1281,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] {
@@ -1308,14 +1310,30 @@ 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 */
@@ -1336,23 +1354,67 @@ 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 */
@@ -1392,8 +1454,31 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
   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 */
@@ -1416,7 +1501,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")
 
@@ -1427,7 +1512,21 @@ 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 */
-- 
cgit v1.2.3


From 5c3b19d6fb90d7c3d8f49d120a49d477c6bd5ec9 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 22:57:47 -0400
Subject: Add Element ScalaDoc documentation

Minor updates to Element's documentation to conform with ScalaDoc style.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 3e0ddc0a..a889a89b 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) {
-- 
cgit v1.2.3


From a5de2b79a93e5acda2cf07bf37534e6782055960 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Tue, 14 Aug 2018 22:58:48 -0400
Subject: Add ToBoolable ScalaDoc documentation

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
---
 chiselFrontend/src/main/scala/chisel3/core/Bits.scala | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'chiselFrontend')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index a889a89b..e9458446 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -45,14 +45,15 @@ 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
 
-- 
cgit v1.2.3