ScalaDoc for Mux (examples added) (#1014)

Co-Authored-By: schoeberl <martin@jopdesign.com>
Co-Authored-By: Edward Wang <edward.c.wang@compdigitec.com>
Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

1 files changed, 28 insertions, 1 deletions

diff --git a/src/main/scala/chisel3/util/Mux.scala b/src/main/scala/chisel3/util/Mux.scala
index 245de67e..1fa7518e 100644
--- a/src/main/scala/chisel3/util/Mux.scala
+++ b/src/main/scala/chisel3/util/Mux.scala
@@ -11,6 +11,15 @@ import chisel3.core.SeqUtils
 /** Builds a Mux tree out of the input signal vector using a one hot encoded
   * select signal. Returns the output of the Mux tree.
   *
+  * @example {{{
+  * val hotValue = chisel3.util.Mux1H(Seq(
+  *  io.selector(0) -> 2.U,
+  *  io.selector(1) -> 4.U,
+  *  io.selector(2) -> 8.U,
+  *  io.selector(4) -> 11.U,
+  * ))
+  * }}}
+  *
   * @note results undefined if multiple select signals are simultaneously high
   */
 object Mux1H {
@@ -25,6 +34,14 @@ object Mux1H {
 /** Builds a Mux tree under the assumption that multiple select signals
   * can be enabled. Priority is given to the first select signal.
   *
+  * @example {{{
+  * val hotValue = chisel3.util.PriorityMux(Seq(
+  *  io.selector(0) -> 2.U,
+  *  io.selector(1) -> 4.U,
+  *  io.selector(2) -> 8.U,
+  *  io.selector(4) -> 11.U,
+  * ))
+  * }}}
   * Returns the output of the Mux tree.
   */
 object PriorityMux {
@@ -33,7 +50,13 @@ object PriorityMux {
   def apply[T <: Data](sel: Bits, in: Seq[T]): T = apply((0 until in.size).map(sel(_)), in)
 }
 
-/** Creates a cascade of n Muxs to search for a key value. */
+/** Creates a cascade of n Muxs to search for a key value.
+  *
+  * @example {{{
+  * MuxLookup(idx, default,
+  *     Array(0.U -> a, 1.U -> b))
+  * }}}
+  */
 object MuxLookup {
   /** @param key a key to search for
     * @param default a default value if nothing is found
@@ -50,6 +73,10 @@ object MuxLookup {
 
 /** Given an association of values to enable signals, returns the first value with an associated
   * high enable signal.
+  *
+  * @example {{{
+  * MuxCase(default, Array(c1 -> a, c2 -> b))
+  * }}}
   */
 object MuxCase {
   /** @param default the default value if none are enabled