From 40da27869ba3cd5d06b1f91e964dea42ec337b57 Mon Sep 17 00:00:00 2001
From: Chick Markley
Date: Thu, 16 Feb 2017 12:36:17 -0800
Subject: Add scaladoc examples for Vec and Bundle (#511)

* Add scaladoc examples for Vec and Bundle

* address comments, added @example tag
eliminate extraneous context

* address comments, added @example tag
eliminate extraneous context

* ok, I've wrestled with the javadoc sytnax, the following commit, is my best result so far
---
 .../src/main/scala/chisel3/core/Aggregate.scala    | 54 ++++++++++++++++++++--
 1 file changed, 49 insertions(+), 5 deletions(-)

(limited to 'chiselFrontend/src/main/scala')

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
index cbebe9e1..131719f1 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
@@ -151,11 +151,26 @@ object Vec {
 /** A vector (array) of [[Data]] elements. Provides hardware versions of various
   * collection transformation functions found in software array implementations.
   *
+  * Careful consideration should be given over the use of [[Vec]] vs [[Seq]] or some other scala collection. In
+  * general [[Vec]] only needs to be used when there is a need to express the hardware collection in a [[Reg]]
+  * or IO [[Bundle]] or when access to elements of the array is indexed via a hardware signal.
+  *
+  * Example of indexing into a [[Vec]] using a hardware address and where the [[Vec]] is defined in an IO [[Bundle]]
+  *
+  *  {{{
+  *    val io = IO(new Bundle {
+  *      val in = Input(Vec(20, UInt(16.W)))
+  *      val addr = UInt(5.W)
+  *      val out = Output(UInt(16.W))
+  *    })
+  *    io.out := io.in(io.addr)
+  *  }}}
+  *
   * @tparam T type of elements
-  * @note when multiple conflicting assignments are performed on a Vec element,
-  * the last one takes effect (unlike Mem, where the result is undefined)
-  * @note Vecs, unlike classes in Scala's collection library, are propagated
-  * intact to FIRRTL as a vector type, which may make debugging easier
+  *
+  * @note
+  *  - when multiple conflicting assignments are performed on a Vec element, the last one takes effect (unlike Mem, where the result is undefined)
+  *  - Vecs, unlike classes in Scala's collection library, are propagated intact to FIRRTL as a vector type, which may make debugging easier
   */
 sealed class Vec[T <: Data] private (gen: => T, val length: Int)
     extends Aggregate with VecLike[T] {
@@ -348,7 +363,7 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
 /** Base class for Aggregates based on key values pairs of String and Data
   *
   * Record should only be extended by libraries and fairly sophisticated generators.
-  * RTL writers should use [[Bundle]].
+  * RTL writers should use [[Bundle]].  See [[Record#elements]] for an example.
   */
 abstract class Record extends Aggregate {
 
@@ -423,6 +438,34 @@ abstract class Record extends Aggregate {
   *
   * Usage: extend this class (either as an anonymous or named class) and define
   * members variables of [[Data]] subtypes to be elements in the Bundle.
+  *
+  * Example of an anonymous IO bundle
+  * {{{
+  *   class MyModule extends Module {
+  *     val io = IO(new Bundle {
+  *       val in = Input(UInt(64.W))
+  *       val out = Output(SInt(128.W))
+  *     })
+  *   }
+  * }}}
+  *
+  * Or as a named class
+  * {{{
+  *   class Packet extends Bundle {
+  *     val header = UInt(16.W)
+  *     val addr   = UInt(16.W)
+  *     val data   = UInt(32.W)
+  *   }
+  *   class MyModule extends Module {
+  *      val io = IO(new Bundle {
+  *        val inPacket = Input(new Packet)
+  *        val outPacket = Output(new Packet)
+  *      })
+  *      val reg = Reg(new Packet)
+  *      reg <> inPacket
+  *      outPacket <> reg
+  *   }
+  * }}}
   */
 class Bundle extends Record {
   override def className = "Bundle"
@@ -431,6 +474,7 @@ class Bundle extends Record {
     *
     * Elements defined earlier in the Bundle are higher order upon
     * serialization. For example:
+    * @example
     * {{{
     *   class MyBundle extends Bundle {
     *     val foo = UInt(16.W)
-- 
cgit v1.2.3