Merge pull request #51 from ucb-bar/faq

Add documentation on some non-intuitive parts

src/main/scala/Chisel/Aggregate.scala

@@ -86,6 +86,8 @@ object Vec {
   * collection transformation functions found in software array implementations.
   *
   * @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)
   */
 sealed class Vec[T <: Data] private (gen: => T, val length: Int)
     extends Aggregate(gen.dir) with VecLike[T] {

src/main/scala/Chisel/Mem.scala

@@ -66,6 +66,9 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId wi
   * Writes take effect on the rising clock edge after the request. Reads are
   * combinational (requests will return data on the same cycle).
   * Read-after-write hazards are not an issue.
+  *
+  * @note when multiple conflicting writes are performed on a Mem element, the
+  * result is undefined (unlike Vec, where the last assignment wins)
   */
 sealed class Mem[T <: Data](t: T, length: Int) extends MemBase(t, length)
 
@@ -92,6 +95,9 @@ object SeqMem {
   * data on the rising edge after the request. Read-after-write behavior (when
   * a read and write to the same address are requested on the same cycle) is
   * undefined.
+  *
+  * @note when multiple conflicting writes are performed on a Mem element, the
+  * result is undefined (unlike Vec, where the last assignment wins)
   */
 sealed class SeqMem[T <: Data](t: T, n: Int) extends MemBase[T](t, n) {
   def read(addr: UInt, enable: Bool): T =

src/main/scala/Chisel/Reg.scala

@@ -27,10 +27,20 @@ object Reg {
     * empty to not update unless assigned to using the := operator)
     * @param init: initialization value on reset (or empty for uninitialized,
     * where the register value persists across a reset)
+    *
+    * @note this may result in a type error if called from a type parameterized
+    * function, since the Scala compiler isn't smart enough to know that null
+    * is a valid value. In those cases, you can either use the outType only Reg
+    * constructor or pass in `null.asInstanceOf[T]`.
     */
   def apply[T <: Data](t: T = null, next: T = null, init: T = null): T = {
-    // REVIEW TODO: rewrite this in a less brittle way, perhaps also in a way
-    // that doesn't need two implementations of apply()
+    // TODO: write this in a way that doesn't need nulls (bad Scala style),
+    // null.asInstanceOf[T], and two constructors. Using Option types are an
+    // option, but introduces cumbersome syntax (wrap everything in a Some()).
+    // Implicit conversions to Option (or similar) types were also considered,
+    // but Scala's type inferencer and implicit insertion isn't smart enough
+    // to resolve all use cases. If the type inferencer / implicit resolution
+    // system improves, this may be changed.
     val x = makeType(t, next, init)
     pushCommand(DefRegister(x, Node(x._parent.get.clock), Node(x._parent.get.reset))) // TODO multi-clock
     if (init != null) {