Expand printf documentation

1 files changed, 44 insertions, 13 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Printf.scala b/chiselFrontend/src/main/scala/chisel3/core/Printf.scala
index 87134eda..99d0e06e 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Printf.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Printf.scala
@@ -9,6 +9,10 @@ import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.SourceInfo
 
+/** Prints a message in simulation
+  *
+  * See apply methods for use
+  */
 object printf { // scalastyle:ignore object.name
   /** Helper for packing escape characters */
   private[chisel3] def format(formatIn: String): String = {
@@ -28,30 +32,57 @@ object printf { // scalastyle:ignore object.name
     formatIn map escaped mkString ""
   }
 
-  /** Prints a message in simulation.
+  /** Prints a message in simulation
     *
-    * Does not fire when in reset (defined as the encapsulating Module's
-    * reset). If your definition of reset is not the encapsulating Module's
-    * reset, you will need to gate this externally.
+    * Prints a message every cycle. If defined within the scope of a [[when]] block, the message
+    * will only be printed on cycles that the when condition is true.
     *
-    * May be called outside of a Module (like defined in a function), uses
-    * whatever clock and reset are in scope.
+    * Does not fire when in reset (defined as the encapsulating Module's reset). If your definition
+    * of reset is not the encapsulating Module's reset, you will need to gate this externally.
+    *
+    * May be called outside of a Module (like defined in a function), uses the current default clock
+    * and reset. These can be overriden with [[withClockAndReset]].
+    *
+    * ==Format Strings==
+    *
+    * This method expects a ''format string'' and an ''argument list'' in a similar style to printf
+    * in C. The format string expects a [[scala.Predef.String String]] that may contain ''format
+    * specifiers'' For example:
+    * {{{
+    *   printf("myWire has the value %d\n", myWire)
+    * }}}
+    * This prints the string "myWire has the value " followed by the current value of `myWire` (in
+    * decimal, followed by a newline.
+    *
+    * There must be exactly as many arguments as there are format specifiers
+    *
+    * ===Format Specifiers===
+    *
+    * Format specifiers are prefixed by `%`. If you wish to print a literal `%`, use `%%`.
+    *   - `%d` - Decimal
+    *   - `%x` - Hexadecimal
+    *   - `%b` - Binary
+    *   - `%c` - 8-bit Character
+    *   - `%n` - Name of a signal
+    *   - `%N` - Full name of a leaf signal (in an aggregate)
     *
     * @param fmt printf format string
     * @param data format string varargs containing data to print
     */
   def apply(fmt: String, data: Bits*)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Unit =
     apply(Printable.pack(fmt, data:_*))
-  /** Prints a message in simulation.
+  /** Prints a message in simulation
+    *
+    * Prints a message every cycle. If defined within the scope of a [[when]] block, the message
+    * will only be printed on cycles that the when condition is true.
     *
-    * Does not fire when in reset (defined as the encapsulating Module's
-    * reset). If your definition of reset is not the encapsulating Module's
-    * reset, you will need to gate this externally.
+    * Does not fire when in reset (defined as the encapsulating Module's reset). If your definition
+    * of reset is not the encapsulating Module's reset, you will need to gate this externally.
     *
-    * May be called outside of a Module (like defined in a function), so
-    * functions using printf make the standard Module assumptions (single clock
-    * and single reset).
+    * May be called outside of a Module (like defined in a function), uses the current default clock
+    * and reset. These can be overriden with [[withClockAndReset]].
     *
+    * @see [[Printable]] documentation
     * @param pable [[Printable]] to print
     */
   def apply(pable: Printable)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Unit = {