Improve some of the ScalaDoc in chisel3.util

1 files changed, 21 insertions, 13 deletions

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
 }