Update docs on dontTouch as optimization barrier (#2015)

Change the Scaladoc for the dontTouch utility.  Indicate that this is an
_optimization barrier_ and not just a guarantee that the signal won't be
removed.  The optimization barrier interpretation is the current
implementation in the Scala FIRRTL Compiler.

Signed-off-by: Schuyler Eldridge <[email protected]>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

core/src/main/scala/chisel3/dontTouch.scala

@@ -5,7 +5,8 @@ package chisel3
 import chisel3.experimental.{ChiselAnnotation, annotate, requireIsHardware}
 import firrtl.transforms.DontTouchAnnotation
 
-/** Marks that a signal should not be removed by Chisel and Firrtl optimization passes
+/** Marks that a signal is an optimization barrier to Chisel and the FIRRTL compiler. This has the effect of
+  * guaranteeing that a signal will not be removed.
   *
   * @example {{{
   * class MyModule extends Module {
@@ -21,9 +22,11 @@ import firrtl.transforms.DontTouchAnnotation
   * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
   * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
   * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
+  * @note Because this is an optimization barrier, constants will not be propagated through a signal marked as
+  * dontTouch.
   */
 object dontTouch {
-  /** Marks a signal to be preserved in Chisel and Firrtl
+  /** Mark a signal as an optimization barrier to Chisel and FIRRTL.
     *
     * @note Requires the argument to be bound to hardware
     * @param data The signal to be marked