Merge branch 'master' into gsdt

21 files changed, 293 insertions, 152 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 8b3723f5..938eeb1f 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -771,6 +771,11 @@ sealed class Bool(lit: Option[ULit] = None) extends UInt(Width(1), lit) {
   def && (that: Bool): Bool = macro SourceInfoTransform.thatArg
 
   def do_&& (that: Bool)(implicit sourceInfo: SourceInfo): Bool = this & that
+
+  /** Reinterprets this Bool as a Clock.  */
+  def asClock(): Clock = macro SourceInfoTransform.noArg
+
+  def do_asClock(implicit sourceInfo: SourceInfo): Clock = pushOp(DefPrim(sourceInfo, Clock(), AsClockOp, ref))
 }
 
 object Bool {
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 69c375f1..4bb58572 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -5,9 +5,10 @@ package chisel3.core
 import scala.language.experimental.macros
 
 import chisel3.internal._
-import chisel3.internal.Builder.pushCommand
+import chisel3.internal.Builder.{pushCommand, pushOp}
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{SourceInfo, DeprecatedSourceInfo, UnlocatableSourceInfo, WireTransform, SourceInfoTransform}
+import chisel3.internal.firrtl.PrimOp.AsUIntOp
 import chisel3.NotStrict.CompileOptions
 
 sealed abstract class Direction(name: String) {
@@ -298,4 +299,6 @@ sealed class Clock extends Element(Width(1)) {
 
   /** Not really supported */
   def toPrintable: Printable = PString("CLOCK")
+
+  override def do_asUInt(implicit sourceInfo: SourceInfo): UInt = pushOp(DefPrim(sourceInfo, UInt(this.width), AsUIntOp, ref))
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Module.scala b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
index 9f7048cd..03e4f1b7 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Module.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
@@ -130,7 +130,7 @@ extends HasId {
   private[chisel3] def addId(d: HasId) { _ids += d }
 
   private[core] def ports: Seq[(String,Data)] = Vector(
-    ("clk", clock), ("reset", reset), ("io", io)
+    ("clock", clock), ("reset", reset), ("io", io)
   )
 
   private[core] def computePorts: Seq[firrtl.Port] = {
diff --git a/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala b/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
index 63bcc87f..0d8604cd 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/SeqUtils.scala
@@ -7,7 +7,12 @@ import scala.language.experimental.macros
 import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform}
 
 private[chisel3] object SeqUtils {
-  /** Equivalent to Cat(r(n-1), ..., r(0)) */
+  /** Concatenates the data elements of the input sequence, in sequence order, together.
+    * The first element of the sequence forms the least significant bits, while the last element
+    * in the sequence forms the most significant bits.
+    *
+    * Equivalent to r(n-1) ## ... ## r(1) ## r(0).
+    */
   def asUInt[T <: Bits](in: Seq[T]): UInt = macro SourceInfoTransform.inArg
 
   def do_asUInt[T <: Bits](in: Seq[T])(implicit sourceInfo: SourceInfo): UInt = {
@@ -20,7 +25,8 @@ private[chisel3] object SeqUtils {
     }
   }
 
-  /** Counts the number of true Bools in a Seq */
+  /** Outputs the number of elements that === Bool(true).
+    */
   def count(in: Seq[Bool]): UInt = macro SourceInfoTransform.inArg
 
   def do_count(in: Seq[Bool])(implicit sourceInfo: SourceInfo): UInt = in.size match {
@@ -29,7 +35,8 @@ private[chisel3] object SeqUtils {
     case n => count(in take n/2) +& count(in drop n/2)
   }
 
-  /** Returns data value corresponding to first true predicate */
+  /** Returns the data value corresponding to the first true predicate.
+    */
   def priorityMux[T <: Data](in: Seq[(Bool, T)]): T = macro SourceInfoTransform.inArg
 
   def do_priorityMux[T <: Data](in: Seq[(Bool, T)])(implicit sourceInfo: SourceInfo): T = {
@@ -40,7 +47,10 @@ private[chisel3] object SeqUtils {
     }
   }
 
-  /** Returns data value corresponding to lone true predicate */
+  /** Returns the data value corresponding to the lone true predicate.
+    *
+    * @note assumes exactly one true predicate, results undefined otherwise
+    */
   def oneHotMux[T <: Data](in: Iterable[(Bool, T)]): T = macro SourceInfoTransform.inArg
 
   def do_oneHotMux[T <: Data](in: Iterable[(Bool, T)])(implicit sourceInfo: SourceInfo): T = {
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
index 1f05b6e2..0641686c 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
@@ -42,6 +42,7 @@ object PrimOp {
   val ConvertOp = PrimOp("cvt")
   val AsUIntOp = PrimOp("asUInt")
   val AsSIntOp = PrimOp("asSInt")
+  val AsClockOp = PrimOp("asClock")
 }
 
 abstract class Arg {
@@ -166,9 +167,9 @@ case class WhenEnd(sourceInfo: SourceInfo) extends Command
 case class Connect(sourceInfo: SourceInfo, loc: Node, exp: Arg) extends Command
 case class BulkConnect(sourceInfo: SourceInfo, loc1: Node, loc2: Node) extends Command
 case class ConnectInit(sourceInfo: SourceInfo, loc: Node, exp: Arg) extends Command
-case class Stop(sourceInfo: SourceInfo, clk: Arg, ret: Int) extends Command
+case class Stop(sourceInfo: SourceInfo, clock: Arg, ret: Int) extends Command
 case class Component(id: Module, name: String, ports: Seq[Port], commands: Seq[Command]) extends Arg
 case class Port(id: Data, dir: Direction)
-case class Printf(sourceInfo: SourceInfo, clk: Arg, pable: Printable) extends Command
+case class Printf(sourceInfo: SourceInfo, clock: Arg, pable: Printable) extends Command
 
 case class Circuit(name: String, components: Seq[Component])
diff --git a/src/main/resources/top.cpp b/src/main/resources/top.cpp
index 8bfe2a99..075d7085 100644
--- a/src/main/resources/top.cpp
+++ b/src/main/resources/top.cpp
@@ -44,10 +44,10 @@ int main(int argc, char** argv) {
       top->reset = 0;   // Deassert reset
     }
     if ((main_time % 10) == 1) {
-      top->clk = 1;       // Toggle clock
+      top->clock = 1;       // Toggle clock
     }
     if ((main_time % 10) == 6) {
-      top->clk = 0;
+      top->clock = 0;
     }
     top->eval();               // Evaluate model
 #if VM_TRACE
@@ -69,10 +69,10 @@ int main(int argc, char** argv) {
   vluint64_t end_time = main_time + 100;
   while (main_time < end_time) {
     if ((main_time % 10) == 1) {
-      top->clk = 1;       // Toggle clock
+      top->clock = 1;       // Toggle clock
     }
     if ((main_time % 10) == 6) {
-      top->clk = 0;
+      top->clock = 0;
     }
     top->eval();               // Evaluate model
 #if VM_TRACE
diff --git a/src/main/scala/chisel3/internal/firrtl/Emitter.scala b/src/main/scala/chisel3/internal/firrtl/Emitter.scala
index 8849077d..f1908089 100644
--- a/src/main/scala/chisel3/internal/firrtl/Emitter.scala
+++ b/src/main/scala/chisel3/internal/firrtl/Emitter.scala
@@ -24,10 +24,10 @@ private class Emitter(circuit: Circuit) {
       case e: DefMemPort[_] => s"${e.dir} mport ${e.name} = ${e.source.fullName(ctx)}[${e.index.fullName(ctx)}], ${e.clock.fullName(ctx)}"
       case e: Connect => s"${e.loc.fullName(ctx)} <= ${e.exp.fullName(ctx)}"
       case e: BulkConnect => s"${e.loc1.fullName(ctx)} <- ${e.loc2.fullName(ctx)}"
-      case e: Stop => s"stop(${e.clk.fullName(ctx)}, UInt<1>(1), ${e.ret})"
+      case e: Stop => s"stop(${e.clock.fullName(ctx)}, UInt<1>(1), ${e.ret})"
       case e: Printf =>
         val (fmt, args) = e.pable.unpack(ctx)
-        val printfArgs = Seq(e.clk.fullName(ctx), "UInt<1>(1)",
+        val printfArgs = Seq(e.clock.fullName(ctx), "UInt<1>(1)",
           "\"" + printf.format(fmt) + "\"") ++ args
         printfArgs mkString ("printf(", ", ", ")")
       case e: DefInvalid => s"${e.arg.fullName(ctx)} is invalid"
diff --git a/src/main/scala/chisel3/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala
index c80f1908..67e28617 100644
--- a/src/main/scala/chisel3/util/Arbiter.scala
+++ b/src/main/scala/chisel3/util/Arbiter.scala
@@ -8,16 +8,21 @@ package chisel3.util
 import chisel3._
 import chisel3.NotStrict.CompileOptions
 
-/** 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  = Flipped(Vec(n, Decoupled(gen)))
   val out = Decoupled(gen)
   val chosen = Output(UInt.width(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))
@@ -82,25 +87,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 = IO(new ArbiterIO(gen, n))
 
diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
index 5de7a508..972010a6 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 1d48ec0a..289d27b1 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/Cat.scala b/src/main/scala/chisel3/util/Cat.scala
index 469bf9ab..ba12a7d4 100644
--- a/src/main/scala/chisel3/util/Cat.scala
+++ b/src/main/scala/chisel3/util/Cat.scala
@@ -6,16 +6,15 @@ import chisel3._
 import chisel3.core.SeqUtils
 
 object Cat {
-  /** Combine data elements together
-    * @param a Data to combine with
-    * @param r any number of other Data elements to be combined in order
-    * @return A UInt which is all of the bits combined together
+  /** Concatenates the argument data elements, in argument order, together.
     */
   def apply[T <: Bits](a: T, r: T*): UInt = apply(a :: r.toList)
 
-  /** Combine data elements together
-    * @param r any number of other Data elements to be combined in order
-    * @return A UInt which is all of the bits combined together
+  /** Concatenates the data elements of the input sequence, in reverse sequence order, together.
+    * The first element of the sequence forms the most significant bits, while the last element
+    * in the sequence forms the least significant bits.
+    *
+    * Equivalent to r(0) ## r(1) ## ... ## r(n-1).
     */
   def apply[T <: Bits](r: Seq[T]): UInt = SeqUtils.asUInt(r.reverse)
 }
diff --git a/src/main/scala/chisel3/util/CircuitMath.scala b/src/main/scala/chisel3/util/CircuitMath.scala
index c809e14b..d478e10e 100644
--- a/src/main/scala/chisel3/util/CircuitMath.scala
+++ b/src/main/scala/chisel3/util/CircuitMath.scala
@@ -7,13 +7,11 @@ package chisel3.util
 
 import chisel3._
 
-/** Compute the base-2 integer logarithm of a UInt
-  * @example
-  * {{{ data_out := Log2(data_in) }}}
-  * @note The result is truncated, so e.g. Log2(13.U) = 3
-  */
 object Log2 {
-  /** Compute the Log2 on the least significant n bits of x */
+  /** Returns the base-2 integer logarithm of the least-significant `width` bits of an UInt.
+    *
+    * @note The result is truncated, so e.g. Log2(UInt(13)) === UInt(3)
+    */
   def apply(x: Bits, width: Int): UInt = {
     if (width < 2) {
       UInt(0)
@@ -30,6 +28,10 @@ object Log2 {
     }
   }
 
+  /** Returns the base-2 integer logarithm of an UInt.
+    *
+    * @note The result is truncated, so e.g. Log2(UInt(13)) === UInt(3)
+    */
   def apply(x: Bits): UInt = apply(x, x.getWidth)
 
   private def divideAndConquerThreshold = 4
diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index 6218feb0..5830e014 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -12,50 +12,71 @@ import scala.reflect.macros.blackbox._
 
 import chisel3._
 
-/** This is identical to [[Chisel.when when]] with the condition inverted */
 object unless {  // scalastyle:ignore object.name
+  /** Does the same thing as [[when$ when]], but with the condition inverted.
+    */
   def apply(c: Bool)(block: => Unit) {
     when (!c) { block }
   }
 }
 
+/** Implementation details for [[switch]]. See [[switch]] and [[chisel3.util.is is]] for the
+  * user-facing API.
+  */
 class SwitchContext[T <: Bits](cond: T) {
   def is(v: Iterable[T])(block: => Unit) {
-    if (!v.isEmpty) when (v.map(_.asUInt === cond.asUInt).reduce(_||_)) { block }
+    if (!v.isEmpty) {
+      when (v.map(_.asUInt === cond.asUInt).reduce(_||_)) {
+        block
+      }
+    }
   }
   def is(v: T)(block: => Unit) { is(Seq(v))(block) }
   def is(v: T, vr: T*)(block: => Unit) { is(v :: vr.toList)(block) }
 }
 
-/** An object for separate cases in [[Chisel.switch switch]]
-  * It is equivalent to a [[Chisel.when$ when]] block comparing to the condition
-  * Use outside of a switch statement is illegal */
+/** Use to specify cases in a [[switch]] block, equivalent to a [[when$ when]] block comparing to
+  * the condition variable.
+  *
+  * @note illegal outside a [[switch]] block
+  * @note multiple conditions may fire simultaneously
+  * @note dummy implementation, a macro inside [[switch]] transforms this into the actual
+  * implementation
+  */
 object is {   // scalastyle:ignore object.name
-  // Begin deprecation of non-type-parameterized is statements.
+  // TODO: Begin deprecation of non-type-parameterized is statements.
+  /** Executes `block` if the switch condition is equal to any of the values in `v`.
+    */
   def apply(v: Iterable[Bits])(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 
+  /** Executes `block` if the switch condition is equal to `v`.
+    */
   def apply(v: Bits)(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 
+  /** Executes `block` if the switch condition is equal to any of the values in the argument list.
+    */
   def apply(v: Bits, vr: Bits*)(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 }
 
-/** Conditional logic to form a switch block
-  * @example
-  * {{{ ... // default values here
-  * switch ( myState ) {
-  *   is( state1 ) {
-  *     ... // some logic here
+/** Conditional logic to form a switch block. See [[is$ is]] for the case API.
+  *
+  * @example {{{
+  * switch (myState) {
+  *   is (state1) {
+  *     // some logic here that runs when myState === state1
   *   }
-  *   is( state2 ) {
-  *     ... // some logic here
+  *   is (state2) {
+  *     // some logic here that runs when myState === state2
   *   }
-  * } }}}*/
+  * }
+  * }}}
+  */
 object switch {  // scalastyle:ignore object.name
   def apply[T <: Bits](cond: T)(x: => Unit): Unit = macro impl
   def impl(c: Context)(cond: c.Tree)(x: c.Tree): c.Tree = { import c.universe._
diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala
index 441f5c5b..5d9b8c3c 100644
--- a/src/main/scala/chisel3/util/Counter.scala
+++ b/src/main/scala/chisel3/util/Counter.scala
@@ -6,12 +6,14 @@ import chisel3._
 import chisel3.Strict.CompileOptions
 
 /** A counter module
+ *
   * @param n number of counts before the counter resets (or one more than the
   * maximum output value of the counter), need not be a power of two
   */
 class Counter(val n: Int) {
   require(n >= 0)
   val value = if (n > 1) Reg(init=UInt(0, log2Up(n))) else UInt(0)
+
   /** Increment the counter, returning whether the counter currently is at the
     * maximum and will wrap. The incremented value is registered and will be
     * visible on the next cycle.
@@ -30,14 +32,27 @@ class Counter(val n: Int) {
   }
 }
 
-/** Counter Object
-  * Example Usage:
-  * {{{ val countOn = Bool(true) // increment counter every clock cycle
-  * val (myCounterValue, myCounterWrap) = Counter(countOn, n)
-  * when ( myCounterValue === UInt(3) ) { ... } }}}*/
 object Counter
 {
+  /** Instantiate a [[Counter! counter]] with the specified number of counts.
+    */
   def apply(n: Int): Counter = new Counter(n)
+
+  /** Instantiate a [[Counter! counter]] with the specified number of counts and a gate.
+   *
+    * @param cond condition that controls whether the counter increments this cycle
+    * @param n number of counts before the counter resets
+    * @return tuple of the counter value and whether the counter will wrap (the value is at
+    * maximum and the condition is true).
+    *
+    * @example {{{
+    * val countOn = Bool(true) // increment counter every clock cycle
+    * val (counterValue, counterWrap) = Counter(countOn, 4)
+    * when (counterValue === UInt(3)) {
+    *   ...
+    * }
+    * }}}
+    */
   def apply(cond: Bool, n: Int): (UInt, Bool) = {
     val c = new Counter(n)
     var wrap: Bool = null
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 3c9da06a..36502862 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -62,15 +62,26 @@ object ReadyValidIO {
   }
 }
 
-object Decoupled {
-  /** Adds a ready-valid handshaking protocol to any interface.
-    * The standard used is that the consumer uses the flipped interface.
-    */
+/** 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 signaling
+  * of ready or valid.
+  */
+class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
+{
+  override def cloneType: this.type = new DecoupledIO(gen).asInstanceOf[this.type]
+}
+
+/** This factory adds a decoupled handshaking protocol to a data bundle. */
+object Decoupled
+{
+  /** 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(getFirrtlDirection(irr.bits) == OUTPUT, "Only safe to cast produced Irrevocable bits to Decoupled.")
@@ -85,17 +96,6 @@ object Decoupled {
 //  }
 }
 
-/** A concrete subclass of ReadyValidIO signalling 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
-  * of ready or valid.
-  */
-class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
-{
-  override def cloneType: this.type = new DecoupledIO(gen).asInstanceOf[this.type]
-}
-
 /** A concrete subclass of ReadyValidIO that promises to not change
   * the value of 'bits' after a cycle where 'valid' is high and 'ready' is low.
   * Additionally, once 'valid' is raised it will never be lowered until after
@@ -111,9 +111,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(getFirrtlDirection(dec.bits) == INPUT, "Only safe to cast consumed Decoupled bits to Irrevocable.")
@@ -153,10 +154,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,
@@ -220,12 +222,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.
+  *
+  * @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 usage:
-  *   {{{ consumer.io.in <> Queue(producer.io.out, 16) }}}
+  * @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 7146af7e..e3c29e79 100644
--- a/src/main/scala/chisel3/util/LFSR.scala
+++ b/src/main/scala/chisel3/util/LFSR.scala
@@ -9,12 +9,13 @@ import chisel3._
 import chisel3.Strict.CompileOptions
 
 // 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
diff --git a/src/main/scala/chisel3/util/OneHot.scala b/src/main/scala/chisel3/util/OneHot.scala
index 7e04a8d7..53ba8c3d 100644
--- a/src/main/scala/chisel3/util/OneHot.scala
+++ b/src/main/scala/chisel3/util/OneHot.scala
@@ -7,8 +7,12 @@ package chisel3.util
 
 import chisel3._
 
-/** Converts from One Hot Encoding to a UInt indicating which bit is active
-  * This is the inverse of [[Chisel.UIntToOH UIntToOH]]*/
+/** Returns the bit position of the sole high bit of the input bitvector.
+  *
+  * Inverse operation of [[UIntToOH]].
+  *
+  * @note assumes exactly one high bit, results undefined otherwise
+  */
 object OHToUInt {
   def apply(in: Seq[Bool]): UInt = apply(Cat(in.reverse), in.size)
   def apply(in: Vec[Bool]): UInt = apply(in.asUInt, in.size)
@@ -26,9 +30,9 @@ object OHToUInt {
   }
 }
 
-/** @return the bit position of the trailing 1 in the input vector
-  * with the assumption that multiple bits of the input bit vector can be set
-  * @example {{{ data_out := PriorityEncoder(data_in) }}}
+/** Returns the bit position of the least-significant high bit of the input bitvector.
+  *
+  * Multiple bits may be high in the input.
   */
 object PriorityEncoder {
   def apply(in: Seq[Bool]): UInt = PriorityMux(in, (0 until in.size).map(UInt(_)))
@@ -37,8 +41,7 @@ object PriorityEncoder {
 
 /** Returns the one hot encoding of the input UInt.
   */
-object UIntToOH
-{
+object UIntToOH {
   def apply(in: UInt, width: Int = -1): UInt =
     if (width == -1) {
       UInt(1) << in
@@ -47,11 +50,10 @@ object UIntToOH
     }
 }
 
-/** Returns a bit vector in which only the least-significant 1 bit in
-  the input vector, if any, is set.
+/** Returns a bit vector in which only the least-significant 1 bit in the input vector, if any,
+  * is set.
   */
-object PriorityEncoderOH
-{
+object PriorityEncoderOH {
   private def encode(in: Seq[Bool]): UInt = {
     val outs = Seq.tabulate(in.size)(i => UInt(BigInt(1) << i, in.size))
     PriorityMux(in :+ Bool(true), outs :+ UInt(0, in.size))
diff --git a/src/main/scala/chisel3/util/Reg.scala b/src/main/scala/chisel3/util/Reg.scala
index 33508dcd..307812f8 100644
--- a/src/main/scala/chisel3/util/Reg.scala
+++ b/src/main/scala/chisel3/util/Reg.scala
@@ -1,36 +1,42 @@
 // See LICENSE for license details.
 
-/** Variations and helpers for registers.
-  */
-
 package chisel3.util
 
 import chisel3._
 import chisel3.NotStrict.CompileOptions
 
 object RegNext {
-
+  /** Returns a register with the specified next and no reset initialization.
+    *
+    * Essentially a 1-cycle delayed version of the input signal.
+    */
   def apply[T <: Data](next: T): T = Reg[T](null.asInstanceOf[T], next, null.asInstanceOf[T])
 
+  /** Returns a register with the specified next and reset initialization.
+    *
+    * Essentially a 1-cycle delayed version of the input signal.
+    */
   def apply[T <: Data](next: T, init: T): T = Reg[T](null.asInstanceOf[T], next, init)
-
 }
 
 object RegInit {
-
+  /** Returns a register pre-initialized (on reset) to the specified value.
+    */
   def apply[T <: Data](init: T): T = Reg[T](null.asInstanceOf[T], null.asInstanceOf[T], init)
-
 }
 
-/** A register with an Enable signal */
-object RegEnable
-{
+object RegEnable {
+  /** Returns a register with the specified next, update enable gate, and no reset initialization.
+    */
   def apply[T <: Data](updateData: T, enable: Bool): T = {
     val clonedUpdateData = updateData.chiselCloneType
     val r = Reg(clonedUpdateData)
     when (enable) { r := updateData }
     r
   }
+
+  /** Returns a register with the specified next, update enable gate, and reset initialization.
+    */
   def apply[T <: Data](updateData: T, resetData: T, enable: Bool): T = {
     val r = RegInit(resetData)
     when (enable) { r := updateData }
@@ -38,15 +44,15 @@ object RegEnable
   }
 }
 
-/** Returns the n-cycle delayed version of the input signal.
-  */
 object ShiftRegister
 {
-  /** @param in input to delay
+  /** Returns the n-cycle delayed version of the input signal.
+    *
+    * @param in input to delay
     * @param n number of cycles to delay
-    * @param en enable the shift */
-  def apply[T <: Data](in: T, n: Int, en: Bool = Bool(true)): T =
-  {
+    * @param en enable the shift
+    */
+  def apply[T <: Data](in: T, n: Int, en: Bool = Bool(true)): T = {
     // The order of tests reflects the expected use cases.
     if (n == 1) {
       RegEnable(in, en)
diff --git a/src/test/scala/chiselTests/Clock.scala b/src/test/scala/chiselTests/Clock.scala
new file mode 100644
index 00000000..79dd2de4
--- /dev/null
+++ b/src/test/scala/chiselTests/Clock.scala
@@ -0,0 +1,22 @@
+// See LICENSE for license details.
+
+package chiselTests
+
+import org.scalatest._
+import org.scalatest.prop._
+
+import chisel3._
+import chisel3.testers.BasicTester
+import chisel3.util._
+
+class ClockAsUIntTester extends BasicTester {
+  assert(Bool(true).asClock.asUInt === UInt(1))
+  stop()
+}
+
+
+class ClockSpec extends ChiselPropSpec {
+  property("Bool.asClock.asUInt should pass a signal through unaltered") {
+    assertTesterPasses { new ClockAsUIntTester }
+  }
+}