Improve some of the ScalaDoc in chisel3.util

6 files changed, 47 insertions, 32 deletions

diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index 3ebda69b..860ffde3 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -22,6 +22,7 @@ object unless {  // scalastyle:ignore object.name
 
 /** Implementation details for [[switch]]. See [[switch]] and [[chisel3.util.is is]] for the
   * user-facing API.
+  * @note DO NOT USE. This API is subject to change without warning.
   */
 class SwitchContext[T <: Bits](cond: T, whenContext: Option[WhenContext], lits: Set[BigInt]) {
   def is(v: Iterable[T])(block: => Unit): SwitchContext[T] = {
diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala
index aa0c0d43..f6f99f67 100644
--- a/src/main/scala/chisel3/util/Counter.scala
+++ b/src/main/scala/chisel3/util/Counter.scala
@@ -4,10 +4,19 @@ package chisel3.util
 
 import chisel3._
 import chisel3.internal.naming.chiselName  // can't use chisel3_ version because of compile order
-//import chisel3.core.ExplicitCompileOptions.Strict
 
 /** A counter module
- *
+  *
+  * Typically instantiated with apply methods in [[Counter$ object Counter]]
+  *
+  * @example {{{
+  *   val countOn = true.B // increment counter every clock cycle
+  *   val (counterValue, counterWrap) = Counter(countOn, 4)
+  *   when (counterValue === 3.U) {
+  *     ...
+  *   }
+  * }}}
+  *
   * @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
   */
@@ -46,14 +55,6 @@ object Counter
     * @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 = true.B // increment counter every clock cycle
-    * val (counterValue, counterWrap) = Counter(countOn, 4)
-    * when (counterValue === 3.U) {
-    *   ...
-    * }
-    * }}}
     */
   @chiselName
   def apply(cond: Bool, n: Int): (UInt, Bool) = {
diff --git a/src/main/scala/chisel3/util/Enum.scala b/src/main/scala/chisel3/util/Enum.scala
index 6ed0d422..2fdd1a92 100644
--- a/src/main/scala/chisel3/util/Enum.scala
+++ b/src/main/scala/chisel3/util/Enum.scala
@@ -7,25 +7,33 @@ package chisel3.util
 
 import chisel3._
 
+/** Defines a set of unique UInt constants
+  *
+  * Unpack with a list to specify an enumeration. Usually used with [[switch]] to describe a finite
+  * state machine.
+  *
+  * @example {{{
+  * val state_on :: state_off :: Nil = Enum(2)
+  * val current_state = WireInit(state_off)
+  * switch (current_state) {
+  *   is (state_on) {
+  *     ...
+  *   }
+  *   is (state_off) {
+  *     ...
+  *   }
+  * }
+  * }}}
+  */
 trait Enum {
   /** Returns a sequence of Bits subtypes with values from 0 until n. Helper method. */
   protected def createValues(n: Int): Seq[UInt] =
     (0 until n).map(_.U((1 max log2Ceil(n)).W))
 
-  /** Returns n unique UInt values, use with unpacking to specify an enumeration.
+  /** Returns n unique UInt values
     *
-    * @example {{{
-    * val state_on :: state_off :: Nil = Enum(2)
-    * val current_state = UInt()
-    * switch (current_state) {
-    *   is (state_on) {
-    *      ...
-    *   }
-    *   if (state_off) {
-    *      ...
-    *   }
-    * }
-    * }}}
+    * @param n Number of unique UInt constants to enumerate
+    * @return Enumerated constants
     */
   def apply(n: Int): List[UInt] = createValues(n).toList
 }
diff --git a/src/main/scala/chisel3/util/ImplicitConversions.scala b/src/main/scala/chisel3/util/ImplicitConversions.scala
index 712975a7..994ac735 100644
--- a/src/main/scala/chisel3/util/ImplicitConversions.scala
+++ b/src/main/scala/chisel3/util/ImplicitConversions.scala
@@ -6,6 +6,9 @@ import chisel3._
 
 import scala.language.implicitConversions
 
+/** Implicit conversions to automatically convert [[scala.Boolean]] and [[scala.Int]] to [[Bool]]
+  *  and [[UInt]] respectively
+  */
 object ImplicitConversions {
   // The explicit fromIntToLiteral resolves an ambiguous conversion between fromIntToLiteral and
   // UInt.asUInt.
diff --git a/src/main/scala/chisel3/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala
index 7017b7a1..95f0dcea 100644
--- a/src/main/scala/chisel3/util/Valid.scala
+++ b/src/main/scala/chisel3/util/Valid.scala
@@ -24,13 +24,15 @@ object Valid {
 }
 
 /** A hardware module that delays data coming down the pipeline
-  by the number of cycles set by the latency parameter. Functionality
-  is similar to ShiftRegister but this exposes a Pipe interface.
-
-  Example usage:
-    val pipe = new Pipe(UInt())
-    pipe.io.enq <> produce.io.out
-    consumer.io.in <> pipe.io.deq
+  * by the number of cycles set by the latency parameter. Functionality
+  * is similar to ShiftRegister but this exposes a Pipe interface.
+  *
+  * Example usage:
+  * {{{
+  *   val pipe = new Pipe(UInt())
+  *   pipe.io.enq <> produce.io.out
+  *   consumer.io.in <> pipe.io.deq
+  * }}}
   */
 object Pipe
 {
diff --git a/src/main/scala/chisel3/util/util.scala b/src/main/scala/chisel3/util/util.scala
index 129e5d1a..987678e3 100644
--- a/src/main/scala/chisel3/util/util.scala
+++ b/src/main/scala/chisel3/util/util.scala
@@ -2,8 +2,8 @@
 
 package chisel3
 
-/** The util package provides extensions to core chisel for common hardware components and utility functions.
-  *
+/** The util package provides extensions to core chisel for common hardware components and utility
+  * functions
   */
 package object util {