Clarify UseLegacyWidthBehavior ScalaDoc

src/main/scala/chisel3/stage/ChiselAnnotations.scala

@@ -364,23 +364,26 @@ case class DesignAnnotation[DUT <: RawModule](design: DUT) extends NoTargetAnnot
 
 /** Use legacy Chisel width behavior.
   *
-  * '''This should only be used for checking for unexpected semantic changes when bumping to Chisel 7.0.0'''
+  * '''This should only be used for checking for unexpected semantic changes when bumping to Chisel 7.0.0.'''
   *
   * Use as CLI option `--use-legacy-width`.
   *
   * There are two width bugs fixed in Chisel 7.0 that could affect the semantics of user code.
+  * Enabling this option will restore the old, buggy behavior, described below:
   *
   * 1. The width of shift-right when shift amount is >= the width of the argument
   *
-  * This behavior is inconsistent between Chisel and FIRRTL.
-  * - Chisel will report the width of a UInt or SInt shifted right by a number >= its width as a 0-bit value.
-  * - FIRRTL will implement the width for these UInts and SInts as 1-bit.
+  * When this option is enabled, the behavior is as follows:
+  *   - Calling `.getWidth` on the resulting value will report the width as 0.
+  *   - The width of the resulting value will be treated as 1-bit for generating Verilog.
   *
   * 2. The width of `ChiselEnum` values
   *
-  * This behavior is inconsistent between the width reported by Chisel and the FIRRTL emitted by Chisel.
-  * - Calling .getWidth of a ChiselEnum value will give the width needed to encode the enum.
-  * - The resulting FIRRTL will have the minimum width needed to encode the literal value for that enum value.
+  * When this option is enabled, the behavior is as follows:
+  *   - Calling `.getWidth` on a specific ChiselEnum value will give the width needed to encode the enum.
+  *     This is the minimum width needed to encode the maximum value encoded by the enum.
+  *   - The resulting FIRRTL will have the minimum width needed to encode the literal value for just that specific
+  *   enum value.
   */
 case object UseLegacyWidthBehavior
     extends NoTargetAnnotation
@@ -392,7 +395,7 @@ case object UseLegacyWidthBehavior
     new ShellOption[Unit](
       longOption = "use-legacy-width",
       toAnnotationSeq = _ => Seq(UseLegacyWidthBehavior),
-      helpText = "Use legacy (buggy) width behavior (pre Chisel 7.0.0)"
+      helpText = "Use legacy (buggy) width behavior (pre-Chisel 7.0.0)"
     )
   )
 }