Add field grouping ScalaDoc for other subclasses of Bundle (#2214)

* Add field grouping scaladocs for DecoupledIo

* Added groupdesc to DecoupledIO

* Added groupings for IrrevocableIO

* Add groupings for ValidIO

* Add field grouping scaladoc for PRNGIO

* Add field grouping scaladoc for QueueIO

* Added groupings for PipeIO

* Update src/main/scala/chisel3/util/Decoupled.scala

Commited Sugestion

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Decoupled.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Decoupled.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Decoupled.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Decoupled.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Valid.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Valid.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

* Update src/main/scala/chisel3/util/Valid.scala

Co-authored-by: Megan Wachs <megan@sifive.com>

Co-authored-by: Megan Wachs <megan@sifive.com>

3 files changed, 50 insertions, 11 deletions

diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 060a684c..2a098f4d 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -16,6 +16,7 @@ import chisel3.internal.naming._  // can't use chisel3_ version because of compi
   * while the consumer uses the flipped interface (inputs bits).
   * The actual semantics of ready/valid are enforced via the use of concrete subclasses.
   * @param gen the type of data to be wrapped in Ready/Valid
+  * @groupdesc Signals The actual hardware fields of the Bundle
   */
 abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
 {
@@ -26,8 +27,19 @@ abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
     case _ => gen
   }
 
+/** Indicates that the consumer is ready to accept the data this cycle
+  * @group Signals
+  */
   val ready = Input(Bool())
+  
+/** Indicates that the producer has put valid data in 'bits' 
+  * @group Signals
+  */
   val valid = Output(Bool())
+  
+/** The data to be transferred when ready and valid are asserted at the same cycle
+  * @group Signals
+  */
   val bits  = Output(genType)
 }
 
@@ -121,6 +133,7 @@ object Decoupled
   * Additionally, once 'valid' is raised it will never be lowered until after
   * 'ready' has also been raised.
   * @param gen the type of data to be wrapped in IrrevocableIO
+  * @groupdesc Signals The actual hardware fields of the Bundle
   */
 class IrrevocableIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
 
@@ -161,6 +174,7 @@ object DeqIO {
   * @param gen The type of data to queue
   * @param entries The max number of entries in the queue.
   * @param hasFlush A boolean for whether the generated Queue is flushable
+  * @groupdesc Signals The hardware fields of the Bundle
   */
 class QueueIO[T <: Data](private val gen: T, val entries: Int, val hasFlush: Boolean = false) extends Bundle
 { // See github.com/freechipsproject/chisel3/issues/765 for why gen is a private val and proposed replacement APIs.
@@ -169,13 +183,21 @@ class QueueIO[T <: Data](private val gen: T, val entries: Int, val hasFlush: Boo
    *  but internally, the queue implementation itself sits on the other side
    *  of the interface so uses the flipped instance.
    */
-  /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. */
+  /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. 
+    * @group Signals
+    */
   val enq = Flipped(EnqIO(gen))
-  /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]]*/
+  /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]]
+    * @group Signals
+    */
   val deq = Flipped(DeqIO(gen))
-  /** The current amount of data in the queue */
+  /** The current amount of data in the queue 
+    * @group Signals
+    */
   val count = Output(UInt(log2Ceil(entries + 1).W))
-  /** When asserted, reset the enqueue and dequeue pointers, effectively flushing the queue (Optional IO for a flushable Queue)*/ 
+  /** When asserted, reset the enqueue and dequeue pointers, effectively flushing the queue (Optional IO for a flushable Queue)
+    * @group Signals
+    */ 
   val flush = if (hasFlush) Some(Input(Bool())) else None
 
 }
diff --git a/src/main/scala/chisel3/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala
index 4d348014..5d80502a 100644
--- a/src/main/scala/chisel3/util/Valid.scala
+++ b/src/main/scala/chisel3/util/Valid.scala
@@ -17,12 +17,17 @@ import chisel3._
   * @tparam T the type of the data
   * @param gen some data
   * @see [[Valid$ Valid factory]] for concrete examples
+  * @groupdesc Signals The actual hardware fields of the Bundle
   */
 class Valid[+T <: Data](gen: T) extends Bundle {
-  /** A bit that will be asserted when `bits` is valid */
+  /** A bit that will be asserted when `bits` is valid 
+    * @group Signals
+    */
   val valid = Output(Bool())
 
-  /** Some data */
+  /** The data to be transferred, qualified by `valid`
+    * @group Signals
+    */
   val bits  = Output(gen)
 
   /** True when `valid` is asserted
@@ -173,13 +178,18 @@ class Pipe[T <: Data](val gen: T, val latency: Int = 1)(implicit compileOptions:
 
   /** Interface for [[Pipe]]s composed of a [[Valid]] input and [[Valid]] output
     * @define notAQueue
+    * @groupdesc Signals Hardware fields of the Bundle
     */
   class PipeIO extends Bundle {
 
-    /** [[Valid]] input */
+    /** [[Valid]] input 
+      * @group Signals
+      */
     val enq = Input(Valid(gen))
 
-    /** [[Valid]] output. Data will appear here `latency` cycles after being valid at `enq`. */
+    /** [[Valid]] output. Data will appear here `latency` cycles after being valid at `enq`. 
+      * @group Signals
+      */
     val deq = Output(Valid(gen))
   }
 
diff --git a/src/main/scala/chisel3/util/random/PRNG.scala b/src/main/scala/chisel3/util/random/PRNG.scala
index 9b42acf1..3a44385a 100644
--- a/src/main/scala/chisel3/util/random/PRNG.scala
+++ b/src/main/scala/chisel3/util/random/PRNG.scala
@@ -7,16 +7,23 @@ import chisel3.util.Valid
 
 /** Pseudo Random Number Generators (PRNG) interface
   * @param n the width of the LFSR
+  * @groupdesc Signals The actual hardware fields of the Bundle
   */
 class PRNGIO(val n: Int) extends Bundle {
 
-  /** A [[chisel3.util.Valid Valid]] interface that can be used to set the seed (internal PRNG state) */
+  /** A [[chisel3.util.Valid Valid]] interface that can be used to set the seed (internal PRNG state) 
+    * @group Signals
+    */
   val seed: Valid[Vec[Bool]] = Input(Valid(Vec(n, Bool())))
 
-  /** When asserted, the PRNG will increment by one */
+  /** When asserted, the PRNG will increment by one 
+    * @group Signals
+    */
   val increment: Bool = Input(Bool())
 
-  /** The current state of the PRNG */
+  /** The current state of the PRNG 
+    * @group Signals
+    */
   val out: Vec[Bool] = Output(Vec(n, Bool()))
 }