Added documentation to Decoupled, Conditionals, Counter (#1015)

* Added documentation to Decoupled, Conditionals, Counter

* Fixed private Counter class error

* Move Counter class deprecation and re-definition into util package object.

* Revert "Move Counter class deprecation and re-definition into util package object."

This reverts commit f61bdddf7051522363e1d203fcd46b512047c87d.

* Restore the old Counter definition and address this in a separate PR.
We can move the deprecation warning and the type definition into the util package object (see f61bdddf7051522363e1d203fcd46b512047c87d), but then we fail tests using Counter with a `ScalaReflectionException` in Aggregate.scala:779 (in def cloneType) when:
`Some(mirror.reflect(this).symbol)` generates `type Counter is not a class`.

* Made @ducky64 change to Counter doc
Used to generate an inline (logic directly in the containing Module, no internal Module is created) hardware counter.

3 files changed, 13 insertions, 1 deletions

diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index c87c2cb6..2459acb8 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -11,6 +11,7 @@ import scala.reflect.macros.blackbox._
 
 import chisel3._
 
+@deprecated("The unless conditional is deprecated, use when(!condition){...} instead", "3.2")
 object unless {  // scalastyle:ignore object.name
   /** Does the same thing as [[when$ when]], but with the condition inverted.
     */
diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala
index f6f99f67..dbfd5bdd 100644
--- a/src/main/scala/chisel3/util/Counter.scala
+++ b/src/main/scala/chisel3/util/Counter.scala
@@ -5,10 +5,13 @@ package chisel3.util
 import chisel3._
 import chisel3.internal.naming.chiselName  // can't use chisel3_ version because of compile order
 
-/** A counter module
+/** Used to generate an inline (logic directly in the containing Module, no internal Module is created)
+  * hardware counter.
   *
   * Typically instantiated with apply methods in [[Counter$ object Counter]]
   *
+  * Does not create a new Chisel Module
+  *
   * @example {{{
   *   val countOn = true.B // increment counter every clock cycle
   *   val (counterValue, counterWrap) = Counter(countOn, 4)
@@ -59,6 +62,11 @@ object Counter
   @chiselName
   def apply(cond: Bool, n: Int): (UInt, Bool) = {
     val c = new Counter(n)
+    // Note this use of var is generally frowned upon! Don't use this as an example.
+    // This is done because we wanted the hardware generated by c.inc() to be wrapped
+    // in a when statement, but still needed to refer to the final value returned by
+    // c.inc() so we could return cond && wrap. Unless you really, really know what
+    // you are doing, IGNORE THIS CODE!!!!!
     var wrap: Bool = null
     when (cond) { wrap = c.inc() }
     (c.value, cond && wrap)
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 047973f5..0aa72e81 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -34,6 +34,9 @@ abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
 object ReadyValidIO {
 
   implicit class AddMethodsToReadyValid[T<:Data](target: ReadyValidIO[T]) {
+
+    /** Indicates if IO is both ready and valid
+     */
     def fire(): Bool = target.ready && target.valid
 
     /** Push dat onto the output bits of this interface to let the consumer know it has happened.