Merge pull request #291 from ucb-bar/utilscaladocs

Scaladocs for utils

1 files changed, 20 insertions, 5 deletions

diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala
index 1c95190b..4b20158f 100644
--- a/src/main/scala/chisel3/util/Counter.scala
+++ b/src/main/scala/chisel3/util/Counter.scala
@@ -5,12 +5,14 @@ package chisel3.util
 import chisel3._
 
 /** 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.
@@ -29,14 +31,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