Util doc lsfr (#1021)

* Update documentation for LSFR16
- Moved bulk of comments to object.
- Added an example
- Added functional test
- example based on section of test

* Update documentation for LSFR16
- Moved bulk of comments to object.
- Added an example
- Added functional test
- example based on section of test

* Update documentation for LSFR16
- Fixed typos in LFSR
- Reduce trials a little
- Add test of LFSR period

* Update documentation for LSFR16
- Fixed remaining LSFR, arrgh
- Removed intellij specific warning suppressor
- Fixed comments/scaladoc wording and case.

* Update documentation for LSFR16
- Use printable interpolator as example of printing out a Vec

1 files changed, 18 insertions, 3 deletions

diff --git a/src/main/scala/chisel3/util/LFSR.scala b/src/main/scala/chisel3/util/LFSR.scala
index ff2bf840..3b112973 100644
--- a/src/main/scala/chisel3/util/LFSR.scala
+++ b/src/main/scala/chisel3/util/LFSR.scala
@@ -7,13 +7,28 @@ package chisel3.util
 
 import chisel3._
 import chisel3.internal.naming.chiselName  // can't use chisel3_ version because of compile order
-//import chisel3.core.ExplicitCompileOptions.Strict
 
+/** LFSR16 generates a 16-bit linear feedback shift register, returning the register contents.
+  * This is useful for generating a pseudo-random sequence.
+  *
+  * The example below, taken from the unit tests, creates two 4-sided dice using `LFSR16` primitives:
+  * @example {{{
+  *   val bins = Reg(Vec(8, UInt(32.W)))
+  *
+  *   // Create two 4 sided dice and roll them each cycle.
+  *   // Use tap points on each LFSR so values are more independent
+  *   val die0 = Cat(Seq.tabulate(2) { i => LFSR16()(i) })
+  *   val die1 = Cat(Seq.tabulate(2) { i => LFSR16()(i + 2) })
+  *
+  *   val rollValue = die0 +& die1  // Note +& is critical because sum will need an extra bit.
+  *
+  *   bins(rollValue) := bins(rollValue) + 1.U
+  *
+  * }}}
+  */
 // scalastyle:off magic.number
 object LFSR16 {
   /** Generates a 16-bit linear feedback shift register, returning the register contents.
-    * May be useful for generating a pseudorandom sequence.
-    *
     * @param increment optional control to gate when the LFSR updates.
     */
   @chiselName