Merge pull request #1032 from freechipsproject/fix-scaladoc-warnings

Fix almost all scaladoc warnings, add source links

2 files changed, 32 insertions, 34 deletions

diff --git a/src/main/scala/firrtl/passes/ExpandWhens.scala b/src/main/scala/firrtl/passes/ExpandWhens.scala
index 9136c913..560a1c1c 100644
--- a/src/main/scala/firrtl/passes/ExpandWhens.scala
+++ b/src/main/scala/firrtl/passes/ExpandWhens.scala
@@ -14,16 +14,16 @@ import collection.mutable
 import collection.immutable.ListSet
 
 /** Expand Whens
-*
-* This pass does the following things:
-* $ - Remove last connect semantics
-* $ - Remove conditional blocks
-* $ - Eliminate concept of scoping
-* $ - Consolidate attaches
-*
-* @note Assumes bulk connects and isInvalids have been expanded
-* @note Assumes all references are declared
-*/
+  *
+  * This pass does the following things:
+  * $ - Remove last connect semantics
+  * $ - Remove conditional blocks
+  * $ - Eliminate concept of scoping
+  * $ - Consolidate attaches
+  *
+  * @note Assumes bulk connects and isInvalids have been expanded
+  * @note Assumes all references are declared
+  */
 object ExpandWhens extends Pass {
   /** Returns circuit with when and last connection semantics resolved */
   def run(c: Circuit): Circuit = {
@@ -79,23 +79,22 @@ object ExpandWhens extends Pass {
 
     val infoMap: InfoMap = new InfoMap
 
-    /**
-      * Adds into into map, aggregates info into MultiInfo where necessary
-      * @param key  serialized name of node
-      * @param info info being recorded
-      */
+    /* Adds into into map, aggregates info into MultiInfo where necessary
+     * @param key  serialized name of node
+     * @param info info being recorded
+     */
     def saveInfo(key: String, info: Info): Unit = {
       infoMap(key) = infoMap(key) ++ info
     }
 
-    /** Removes connections/attaches from the statement
-      * Mutates namespace, simlist, nodes, attaches
-      * Mutates input netlist
-      * @param netlist maps references to their values for a given immediate scope
-      * @param defaults sequence of netlists of surrouding scopes, ordered closest to farthest
-      * @param p predicate so far, used to update simulation constructs
-      * @param s statement to expand
-      */
+    /* Removes connections/attaches from the statement
+     * Mutates namespace, simlist, nodes, attaches
+     * Mutates input netlist
+     * @param netlist maps references to their values for a given immediate scope
+     * @param defaults sequence of netlists of surrouding scopes, ordered closest to farthest
+     * @param p predicate so far, used to update simulation constructs
+     * @param s statement to expand
+     */
     def expandWhens(netlist: Netlist,
                     defaults: Defaults,
                     p: Expression)
@@ -137,13 +136,13 @@ object ExpandWhens extends Pass {
         EmptyStmt
       // Expand conditionally, see comments below
       case sx: Conditionally =>
-        /** 1) Recurse into conseq and alt with empty netlist, updated defaults, updated predicate
-          * 2) For each assigned reference (lvalue) in either conseq or alt, get merged value
-          *   a) Find default value from defaults
-          *   b) Create Mux, ValidIf or WInvalid, depending which (or both) conseq/alt assigned lvalue
-          * 3) If a merged value has been memoized, update netlist. Otherwise, memoize then update netlist.
-          * 4) Return conseq and alt declarations, followed by memoized nodes
-          */
+        /* 1) Recurse into conseq and alt with empty netlist, updated defaults, updated predicate
+         * 2) For each assigned reference (lvalue) in either conseq or alt, get merged value
+         *   a) Find default value from defaults
+         *   b) Create Mux, ValidIf or WInvalid, depending which (or both) conseq/alt assigned lvalue
+         * 3) If a merged value has been memoized, update netlist. Otherwise, memoize then update netlist.
+         * 4) Return conseq and alt declarations, followed by memoized nodes
+         */
         val conseqNetlist = new Netlist
         val altNetlist = new Netlist
         val conseqStmt = expandWhens(conseqNetlist, netlist +: defaults, AND(p, sx.pred))(sx.conseq)
@@ -269,4 +268,3 @@ object ExpandWhens extends Pass {
   private def NOT(e: Expression) =
     DoPrim(Eq, Seq(e, zero), Nil, BoolType)
 }
-
diff --git a/src/main/scala/firrtl/passes/RemoveValidIf.scala b/src/main/scala/firrtl/passes/RemoveValidIf.scala
index 5338a911..b9f13139 100644
--- a/src/main/scala/firrtl/passes/RemoveValidIf.scala
+++ b/src/main/scala/firrtl/passes/RemoveValidIf.scala
@@ -7,7 +7,7 @@ import firrtl.ir._
 import Utils.throwInternalError
 import WrappedExpression.weq
 
-/** Remove ValidIf and replace IsInvalid with a connection to zero */
+/** Remove [[firrtl.ir.ValidIf ValidIf]] and replace [[firrtl.ir.IsInvalid IsInvalid]] with a connection to zero */
 object RemoveValidIf extends Pass {
 
   val UIntZero = Utils.zero
@@ -15,8 +15,8 @@ object RemoveValidIf extends Pass {
   val ClockZero = DoPrim(PrimOps.AsClock, Seq(UIntZero), Seq.empty, ClockType)
   val FixedZero = FixedLiteral(BigInt(0), IntWidth(1), IntWidth(0))
 
-  /** Returns an [[Expression]] equal to zero for a given [[GroundType]]
-    * @note Accepts [[Type]] but dyanmically expects [[GroundType]]
+  /** Returns an [[firrtl.ir.Expression Expression]] equal to zero for a given [[firrtl.ir.GroundType GroundType]]
+    * @note Accepts [[firrtl.ir.Type Type]] but dyanmically expects [[firrtl.ir.GroundType GroundType]]
     */
   def getGroundZero(tpe: Type): Expression = tpe match {
     case _: UIntType => UIntZero