ScalaDocs improvement for utils Math, MixedVec (#1019)

2 files changed, 85 insertions, 24 deletions

diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala
index 0e1b36d5..f9278c7d 100644
--- a/src/main/scala/chisel3/util/Math.scala
+++ b/src/main/scala/chisel3/util/Math.scala
@@ -8,7 +8,21 @@ package chisel3.util
 import chisel3._
 import chisel3.internal.chiselRuntimeDeprecated
 
-/** Compute the log2 rounded up with min value of 1 */
+/** Compute the log2 of a Scala integer, rounded up, with min value of 1.
+  * Useful for getting the number of bits needed to represent some number of states (in - 1),
+  * To get the number of bits needed to represent some number n, use log2Up(n + 1).
+  * with the minimum value preventing the creation of currently-unsupported zero-width wires.
+  *
+  * Note: prefer to use log2Ceil when in is known to be > 1 (where log2Ceil(in) > 0).
+  * This will be deprecated when zero-width wires is supported.
+  *
+  * @example {{{
+  * log2Up(1)  // returns 1
+  * log2Up(2)  // returns 1
+  * log2Up(3)  // returns 2
+  * log2Up(4)  // returns 2
+  * }}}
+  */
 object log2Up {
   // Do not deprecate until zero-width wires fully work:
   // https://github.com/freechipsproject/chisel3/issues/847
@@ -17,7 +31,20 @@ object log2Up {
   def apply(in: BigInt): Int = Chisel.log2Up(in)
 }
 
-/** Compute the log2 rounded up */
+/** Compute the log2 of a Scala integer, rounded up.
+  * Useful for getting the number of bits needed to represent some number of states (in - 1).
+  * To get the number of bits needed to represent some number n, use log2Ceil(n + 1).
+  *
+  * Note: can return zero, and should not be used in cases where it may generate unsupported
+  * zero-width wires.
+  *
+  * @example {{{
+  * log2Ceil(1)  // returns 0
+  * log2Ceil(2)  // returns 1
+  * log2Ceil(3)  // returns 2
+  * log2Ceil(4)  // returns 2
+  * }}}
+  */
 object log2Ceil {
   def apply(in: BigInt): Int = {
     require(in > 0)
@@ -26,7 +53,15 @@ object log2Ceil {
   def apply(in: Int): Int = apply(BigInt(in))
 }
 
-/** Compute the log2 rounded down with min value of 1 */
+/** Compute the log2 of a Scala integer, rounded down, with min value of 1.
+  *
+  * @example {{{
+  * log2Down(1)  // returns 1
+  * log2Down(2)  // returns 1
+  * log2Down(3)  // returns 1
+  * log2Down(4)  // returns 2
+  * }}}
+  */
 object log2Down {
   // Do not deprecate until zero-width wires fully work:
   // https://github.com/freechipsproject/chisel3/issues/847
@@ -35,13 +70,31 @@ object log2Down {
   def apply(in: BigInt): Int = Chisel.log2Down(in)
 }
 
-/** Compute the log2 rounded down */
+/** Compute the log2 of a Scala integer, rounded down.
+  *
+  * Can be useful in computing the next-smallest power of two.
+  *
+  * @example {{{
+  * log2Floor(1)  // returns 0
+  * log2Floor(2)  // returns 1
+  * log2Floor(3)  // returns 1
+  * log2Floor(4)  // returns 2
+  * }}}
+  */
 object log2Floor {
   def apply(in: BigInt): Int = log2Ceil(in) - (if (isPow2(in)) 0 else 1)
   def apply(in: Int): Int = apply(BigInt(in))
 }
 
-/** Check if an Integer is a power of 2 */
+/** Returns whether a Scala integer is a power of two.
+  *
+  * @example {{{
+  * isPow2(1)  // returns true
+  * isPow2(2)  // returns true
+  * isPow2(3)  // returns false
+  * isPow2(4)  // returns true
+  * }}}
+  */
 object isPow2 {
   def apply(in: BigInt): Boolean = in > 0 && ((in & (in-1)) == 0)
   def apply(in: Int): Boolean = apply(BigInt(in))
diff --git a/src/main/scala/chisel3/util/MixedVec.scala b/src/main/scala/chisel3/util/MixedVec.scala
index ec15e23a..80e224d3 100644
--- a/src/main/scala/chisel3/util/MixedVec.scala
+++ b/src/main/scala/chisel3/util/MixedVec.scala
@@ -8,12 +8,20 @@ import chisel3.internal.naming.chiselName
 
 import scala.collection.immutable.ListMap
 
+/**
+  * Create a MixedVec wire with default values as specified, and type of each element inferred from
+  * those default values.
+  *
+  * This is analogous to [[chisel3.core.VecInit]].
+  * @return MixedVec with given values assigned
+  *
+  * @example {{{
+  * MixedVecInit(Seq(100.U(8.W), 10000.U(16.W), 101.U(32.W)))
+  * }}}
+  */
 object MixedVecInit {
   /**
-    * Construct a new wire with the given bound values.
-    * This is analogous to [[chisel3.core.VecInit]].
-    * @param vals Values to create a MixedVec with and assign
-    * @return MixedVec with given values assigned
+    * Create a MixedVec wire from a Seq of values.
     */
   def apply[T <: Data](vals: Seq[T]): MixedVec[T] = {
     // Create a wire of this type.
@@ -26,39 +34,39 @@ object MixedVecInit {
   }
 
   /**
-    * Construct a new wire with the given bound values.
-    * This is analogous to [[chisel3.core.VecInit]].
-    * @return MixedVec with given values assigned
+    * Create a MixedVec wire from a varargs list of values.
     */
   def apply[T <: Data](val0: T, vals: T*): MixedVec[T] = apply(val0 +: vals.toSeq)
 }
 
+/**
+  * Create a MixedVec type, given element types. Inputs must be Chisel types which have no value
+  * (not hardware types).
+  *
+  * @return MixedVec with the given types.
+  */
 object MixedVec {
   /**
-    * Create a MixedVec from that holds the given types.
-    * @param eltsIn Element types. Must be Chisel types.
-    * @return MixedVec with the given types.
+    * Create a MixedVec type from a Seq of Chisel types.
     */
   def apply[T <: Data](eltsIn: Seq[T]): MixedVec[T] = new MixedVec(eltsIn)
 
   /**
-    * Create a MixedVec from that holds the given types.
-    * The types passed to this constructor must be Chisel types.
-    * @return MixedVec with the given types.
+    * Create a MixedVec type from a varargs list of Chisel types.
     */
   def apply[T <: Data](val0: T, vals: T*): MixedVec[T] = new MixedVec(val0 +: vals.toSeq)
 
   /**
-    * Create a new MixedVec from an unbound MixedVec type.
-    * @return MixedVec with the given types.
+    * Create a new MixedVec type from an unbound MixedVec type.
     */
   def apply[T <: Data](mixedVec: MixedVec[T]): MixedVec[T] = new MixedVec(mixedVec.elts)
 
   /**
-    * Create a MixedVec from the type of the given Vec.
-    * For example, given a Vec(2, UInt(8.W)), this creates MixedVec(Seq.fill(2){UInt(8.W)}).
-    * @param vec Vec to use as template
-    * @return MixedVec analogous to the given Vec.
+    * Create a MixedVec type from the type of the given Vec.
+    *
+    * @example {{{
+    * MixedVec(Vec(2, UInt(8.W))) = MixedVec(Seq.fill(2){UInt(8.W)})
+    * }}}
     */
   def apply[T <: Data](vec: Vec[T]): MixedVec[T] = {
     MixedVec(Seq.fill(vec.length)(vec.sample_element))