Improved scaladoc in utils and friends

1 files changed, 36 insertions, 14 deletions

diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index 6218feb0..461ff765 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -12,50 +12,72 @@ 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
+/** Conditional logic to form a switch block. See [[is$ is]] for the case API.
+ *
   * @example
-  * {{{ ... // default values here
-  * switch ( myState ) {
-  *   is( state1 ) {
-  *     ... // some logic here
+  * {{{
+  * 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._