Update rest of docs

8 files changed, 123 insertions, 69 deletions

diff --git a/src/main/scala/chisel3/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala
index eb541977..58ba1188 100644
--- a/src/main/scala/chisel3/util/Arbiter.scala
+++ b/src/main/scala/chisel3/util/Arbiter.scala
@@ -7,16 +7,21 @@ package chisel3.util
 
 import chisel3._
 
-/** An I/O bundle for the Arbiter */
+/** IO bundle definition for an Arbiter, which takes some number of ready-valid inputs and outputs
+  * (selects) at most one.
+  *
+  * @param gen data type
+  * @param n number of inputs
+  */
 class ArbiterIO[T <: Data](gen: T, n: Int) extends Bundle {
   val in  = Vec(n, Decoupled(gen)).flip
   val out = Decoupled(gen)
   val chosen = UInt(OUTPUT, log2Up(n))
 }
 
-/** Arbiter Control determining which producer has access */
-private object ArbiterCtrl
-{
+/** Arbiter Control determining which producer has access
+  */
+private object ArbiterCtrl {
   def apply(request: Seq[Bool]): Seq[Bool] = request.length match {
     case 0 => Seq()
     case 1 => Seq(Bool(true))
@@ -81,25 +86,27 @@ class LockingArbiter[T <: Data](gen: T, n: Int, count: Int, needsLock: Option[T
 }
 
 /** Hardware module that is used to sequence n producers into 1 consumer.
-  Producers are chosen in round robin order.
-
-  Example usage:
-    val arb = new RRArbiter(2, UInt())
-    arb.io.in(0) <> producer0.io.out
-    arb.io.in(1) <> producer1.io.out
-    consumer.io.in <> arb.io.out
+  * Producers are chosen in round robin order.
+  *
+  * @example {{{
+  * val arb = new RRArbiter(2, UInt())
+  * arb.io.in(0) <> producer0.io.out
+  * arb.io.in(1) <> producer1.io.out
+  * consumer.io.in <> arb.io.out
+  * }}}
   */
 class RRArbiter[T <: Data](gen:T, n: Int) extends LockingRRArbiter[T](gen, n, 1)
 
 /** Hardware module that is used to sequence n producers into 1 consumer.
- Priority is given to lower producer
-
- Example usage:
-   val arb = Module(new Arbiter(2, UInt()))
-   arb.io.in(0) <> producer0.io.out
-   arb.io.in(1) <> producer1.io.out
-   consumer.io.in <> arb.io.out
- */
+  * Priority is given to lower producer.
+  *
+  * @example {{{
+  * val arb = Module(new Arbiter(2, UInt()))
+  * arb.io.in(0) <> producer0.io.out
+  * arb.io.in(1) <> producer1.io.out
+  * consumer.io.in <> arb.io.out
+  * }}}
+  */
 class Arbiter[T <: Data](gen: T, n: Int) extends Module {
   val io = new ArbiterIO(gen, n)
 
diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
index 26106080..6c012583 100644
--- a/src/main/scala/chisel3/util/BitPat.scala
+++ b/src/main/scala/chisel3/util/BitPat.scala
@@ -37,7 +37,7 @@ object BitPat {
   /** Creates a [[BitPat]] literal from a string.
    *
     * @param n the literal value as a string, in binary, prefixed with 'b'
-    * @note legal characters are '0', '1', and '?', as well as '_' as white
+    * @note legal characters are '0', '1', and '?', as well as '_' and white
     * space (which are ignored)
     */
   def apply(n: String): BitPat = {
diff --git a/src/main/scala/chisel3/util/Bitwise.scala b/src/main/scala/chisel3/util/Bitwise.scala
index 6451ab14..7d5ffe09 100644
--- a/src/main/scala/chisel3/util/Bitwise.scala
+++ b/src/main/scala/chisel3/util/Bitwise.scala
@@ -8,9 +8,18 @@ package chisel3.util
 import chisel3._
 import chisel3.core.SeqUtils
 
-object FillInterleaved
-{
+object FillInterleaved {
+  /** Creates n repetitions of each bit of x in order.
+    *
+    * Output data-equivalent to in(size(in)-1) (n times) ## ... ## in(1) (n times) ## in(0) (n times)
+    * For example, FillInterleaved(2, "b1000") === UInt("b11 00 00 00")
+    */
   def apply(n: Int, in: UInt): UInt = apply(n, in.toBools)
+
+  /** Creates n repetitions of each bit of x in order.
+    *
+    * Output data-equivalent to in(size(in)-1) (n times) ## ... ## in(1) (n times) ## in(0) (n times)
+    */
   def apply(n: Int, in: Seq[Bool]): UInt = Cat(in.map(Fill(n, _)).reverse)
 }
 
@@ -22,9 +31,11 @@ object PopCount
   def apply(in: Bits): UInt = apply((0 until in.getWidth).map(in(_)))
 }
 
-/** Fill fans out a UInt to multiple copies */
 object Fill {
-  /** Fan out x n times */
+  /** Create n repetitions of x using a tree fanout topology.
+    *
+    * Output data-equivalent to x ## x ## ... ## x (n repetitions).
+    */
   def apply(n: Int, x: UInt): UInt = {
     n match {
       case 0 => UInt(width=0)
@@ -42,10 +53,7 @@ object Fill {
   }
 }
 
-/** Litte/big bit endian convertion: reverse the order of the bits in a UInt.
-*/
-object Reverse
-{
+object Reverse {
   private def doit(in: UInt, length: Int): UInt = {
     if (length == 1) {
       in
@@ -65,5 +73,7 @@ object Reverse
       Cat(doit(in(half-1,0), half), doit(in(length-1,half), length-half))
     }
   }
+  /** Returns the input in bit-reversed order. Useful for little/big-endian conversion.
+    */
   def apply(in: UInt): UInt = doit(in, in.getWidth)
 }
diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index 461ff765..5830e014 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -65,9 +65,8 @@ object is {   // scalastyle:ignore object.name
 }
 
 /** Conditional logic to form a switch block. See [[is$ is]] for the case API.
- *
-  * @example
-  * {{{
+  *
+  * @example {{{
   * switch (myState) {
   *   is (state1) {
   *     // some logic here that runs when myState === state1
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 77990777..65558aa9 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -21,10 +21,10 @@ abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
   def fire(dummy: Int = 0): Bool = ready && valid
 }
 
-/** A concrete subclass of ReadyValidIO signalling that the user expects a
+/** A concrete subclass of ReadyValidIO signaling that the user expects a
   * "decoupled" interface: 'valid' indicates that the producer has
   * put valid data in 'bits', and 'ready' indicates that the consumer is ready
-  * to accept the data this cycle. No requirements are placed on the signalling
+  * to accept the data this cycle. No requirements are placed on the signaling
   * of ready or valid.
   */
 class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
@@ -35,12 +35,12 @@ class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
 /** This factory adds a decoupled handshaking protocol to a data bundle. */
 object Decoupled
 {
-  /** Take any Data and wrap it in a DecoupledIO interface */
+  /** Wraps some Data with a DecoupledIO interface. */
   def apply[T <: Data](gen: T): DecoupledIO[T] = new DecoupledIO(gen)
 
-  /** Take an IrrevocableIO and cast it to a DecoupledIO.
-    * This cast is only safe to do in cases where the IrrevocableIO
-    * is being produced as an output.
+  /** Downconverts an IrrevocableIO output to a DecoupledIO, dropping guarantees of irrevocability.
+    *
+    * @note unsafe (and will error) on the producer (input) side of an IrrevocableIO
     */
   def apply[T <: Data](irr: IrrevocableIO[T]): DecoupledIO[T] = {
     require(irr.bits.dir == OUTPUT, "Only safe to cast produced Irrevocable bits to Decoupled.")
@@ -67,9 +67,10 @@ object Irrevocable
 {
   def apply[T <: Data](gen: T): IrrevocableIO[T] = new IrrevocableIO(gen)
 
-  /** Take a DecoupledIO and cast it to an IrrevocableIO.
-    * This cast is only safe to do in cases where the IrrevocableIO
-    * is being consumed as an input.
+  /** Upconverts a DecoupledIO input to an IrrevocableIO, allowing an IrrevocableIO to be used
+    * where a DecoupledIO is expected.
+    *
+    * @note unsafe (and will error) on the consumer (output) side of an DecoupledIO
     */
   def apply[T <: Data](dec: DecoupledIO[T]): IrrevocableIO[T] = {
     require(dec.bits.dir == INPUT, "Only safe to cast consumed Decoupled bits to Irrevocable.")
@@ -156,10 +157,11 @@ class QueueIO[T <: Data](gen: T, entries: Int) extends Bundle
   * @param flow True if the inputs can be consumed on the same cycle (the inputs "flow" through the queue immediately).
   * The ''valid'' signals are coupled.
   *
-  * Example usage:
-  *    {{{ val q = new Queue(UInt(), 16)
-  *    q.io.enq <> producer.io.out
-  *    consumer.io.in <> q.io.deq }}}
+  * @example {{{
+  * val q = new Queue(UInt(), 16)
+  * q.io.enq <> producer.io.out
+  * consumer.io.in <> q.io.deq
+  * }}}
   */
 class Queue[T <: Data](gen: T,
                        val entries: Int,
@@ -223,12 +225,16 @@ extends Module(override_reset=override_reset) {
   }
 }
 
-/** Factory for a generic hardware queue. Required parameter 'entries' controls
-  * the depth of the queues. The width of the queue is determined
-  * from the input 'enq'.
+/** Factory for a generic hardware queue.
   *
-  * Example usage:
-  *   {{{ consumer.io.in <> Queue(producer.io.out, 16) }}}
+  * @param enq input (enqueue) interface to the queue, also determines width of queue elements
+  * @param entries depth (number of elements) of the queue
+  *
+  * @returns output (dequeue) interface from the queue
+  *
+  * @example {{{
+  * consumer.io.in <> Queue(producer.io.out, 16)
+  * }}}
   */
 object Queue
 {
diff --git a/src/main/scala/chisel3/util/Enum.scala b/src/main/scala/chisel3/util/Enum.scala
index 4ecc243b..55b595ee 100644
--- a/src/main/scala/chisel3/util/Enum.scala
+++ b/src/main/scala/chisel3/util/Enum.scala
@@ -12,12 +12,42 @@ object Enum {
   private def createValues[T <: Bits](nodeType: T, n: Int): Seq[T] =
     (0 until n).map(x => nodeType.fromInt(x, log2Up(n)))
 
-  /** create n enum values of given type */
+  /** Returns n unique values of the specified type. Can be used with unpacking to define enums.
+    *
+    * @example {{{
+    * val state_on :: state_off :: Nil = Enum(UInt(), 2)
+    * val current_state = UInt()
+    * switch (current_state) {
+    *   is (state_on) {
+    *      ...
+    *   }
+    *   if (state_off) {
+    *      ...
+    *   }
+    * }
+    * }}}
+    *
+    */
   def apply[T <: Bits](nodeType: T, n: Int): List[T] = createValues(nodeType, n).toList
 
-  /** create enum values of given type and names */
+  /** Returns a map of the input symbols to unique values of the specified type.
+    *
+    * @example {{{
+    * val states = Enum(UInt(), 'on, 'off)
+    * val current_state = UInt()
+    * switch (current_state) {
+    *   is (states('on)) {
+    *     ...
+    *   }
+    *   if (states('off)) {
+    *     ..
+    *   }
+    * }
+    * }}}
+    */
   def apply[T <: Bits](nodeType: T, l: Symbol *): Map[Symbol, T] = (l zip createValues(nodeType, l.length)).toMap
 
-  /** create enum values of given type and names */
+  /** Returns a map of the input symbols to unique values of the specified type.
+    */
   def apply[T <: Bits](nodeType: T, l: List[Symbol]): Map[Symbol, T] = (l zip createValues(nodeType, l.length)).toMap
 }
diff --git a/src/main/scala/chisel3/util/LFSR.scala b/src/main/scala/chisel3/util/LFSR.scala
index a30c276f..e4261c20 100644
--- a/src/main/scala/chisel3/util/LFSR.scala
+++ b/src/main/scala/chisel3/util/LFSR.scala
@@ -8,12 +8,13 @@ package chisel3.util
 import chisel3._
 
 // scalastyle:off magic.number
-/** linear feedback shift register
-  */
-object LFSR16
-{
-  def apply(increment: Bool = Bool(true)): UInt =
-  {
+object LFSR16 {
+  /** Generates a 16-bit linear feedback shift register, returning the register contents.
+    * May be useful for generating a pseudorandom sequence.
+    *
+    * @param increment optional control to gate when the LFSR updates.
+    */
+  def apply(increment: Bool = Bool(true)): UInt = {
     val width = 16
     val lfsr = Reg(init=UInt(1, width))
     when (increment) { lfsr := Cat(lfsr(0)^lfsr(2)^lfsr(3)^lfsr(5), lfsr(width-1,1)) }
diff --git a/src/main/scala/chisel3/util/Mux.scala b/src/main/scala/chisel3/util/Mux.scala
index 9956a7e3..245de67e 100644
--- a/src/main/scala/chisel3/util/Mux.scala
+++ b/src/main/scala/chisel3/util/Mux.scala
@@ -9,10 +9,11 @@ import chisel3._
 import chisel3.core.SeqUtils
 
 /** Builds a Mux tree out of the input signal vector using a one hot encoded
-  select signal. Returns the output of the Mux tree.
+  * select signal. Returns the output of the Mux tree.
+  *
+  * @note results undefined if multiple select signals are simultaneously high
   */
-object Mux1H
-{
+object Mux1H {
   def apply[T <: Data](sel: Seq[Bool], in: Seq[T]): T =
     apply(sel zip in)
   def apply[T <: Data](in: Iterable[(Bool, T)]): T = SeqUtils.oneHotMux(in)
@@ -22,18 +23,17 @@ object Mux1H
 }
 
 /** Builds a Mux tree under the assumption that multiple select signals
-  can be enabled. Priority is given to the first select signal.
-
-  Returns the output of the Mux tree.
+  * can be enabled. Priority is given to the first select signal.
+  *
+  * Returns the output of the Mux tree.
   */
-object PriorityMux
-{
+object PriorityMux {
   def apply[T <: Data](in: Seq[(Bool, T)]): T = SeqUtils.priorityMux(in)
   def apply[T <: Data](sel: Seq[Bool], in: Seq[T]): T = apply(sel zip in)
   def apply[T <: Data](sel: Bits, in: Seq[T]): T = apply((0 until in.size).map(sel(_)), in)
 }
 
-/** MuxLookup creates a cascade of n Muxs to search for a key value */
+/** Creates a cascade of n Muxs to search for a key value. */
 object MuxLookup {
   /** @param key a key to search for
     * @param default a default value if nothing is found
@@ -46,10 +46,11 @@ object MuxLookup {
       res = Mux(k === key, v, res)
     res
   }
-
 }
 
-/** MuxCase returns the first value that is enabled in a map of values */
+/** Given an association of values to enable signals, returns the first value with an associated
+  * high enable signal.
+  */
 object MuxCase {
   /** @param default the default value if none are enabled
     * @param mapping a set of data values with associated enables