Commentary

docs/guide/exe_verilator.rst

@@ -158,28 +158,26 @@ Summary:
 
 .. option:: --clk <signal-name>
 
-   Sometimes it is quite difficult for Verilator to distinguish clock
-   signals from other data signals. Occasionally the clock signals can end
-   up in the checking list of signals which determines if further
-   evaluation is needed. This will heavily degrade the performance of a
-   Verilated model.
-
    With :vlopt:`--clk`, the specified signal-name is taken as a root clock
-   into the model, then Verilator will mark the signal as clocker and
+   into the model; Verilator will mark the signal as clocker and
-   propagate the clocker attribute automatically to other signals derived
+   propagate the clocker attribute automatically to other signals downstream in
-   from that. In this way, Verilator will try to avoid taking the clocker
+   that clock tree.
-   signal into checking list.
 
-   Note signal-name is specified by the RTL hierarchy path. For example,
+   The provided signal-name is specified using a RTL hierarchy path. For
-   v.foo.bar.  If the signal is the input to top-module, the directly the
+   example, v.foo.bar.  If the signal is the input to top-module, then
-   signal name. If you find it difficult to find the exact name, try to use
+   directly provide the signal name. Alternatively, use a
-   a :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the
+   :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the
    signal directly.
 
-   If clock signals are assigned to vectors and then later used
+   If clock signals are assigned to vectors and then later used as
-   individually, Verilator will attempt to decompose the vector and connect
+   individual bits, Verilator will attempt to decompose the vector and
-   the single-bit clock signals directly.  This should be transparent to
+   connect the single-bit clock signals.
-   the user.
+
+   The clocker attribute is useful in cases where Verilator does not
+   properly distinguish clock signals from other data signals. Using
+   clocker will cause the signal indicated to be considered a clock, and
+   remove it from the combinatorial logic reevaluation checking code. This
+   may greatly improve performance.
 
 .. option:: --make <build-tool>
 
@@ -1506,9 +1504,9 @@ The grammar of configuration commands is as follows:
 
 .. option:: no_clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"
 
-   Indicate the signal is used as clock or not. This information is used by
+   Indicates that the signal is used as clock or not. This information is
-   Verilator to mark the signal as clocker and propagate the clocker
+   used by Verilator to mark the signal and any derrived signals as
-   attribute automatically to derived signals. See :vlopt:`--clk`.
+   clocker.  See :vlopt:`--clk`.
 
    Same as :option:`/*verilator&32;clocker*/` metacomment.
 

docs/guide/extensions.rst

@@ -176,10 +176,9 @@ or "`ifdef`"'s may break other tools.
 
 .. option:: /*verilator&32;no_clocker*/
 
-   Used after a signal declaration to indicate the signal is used as clock
+   Specifies that the signal is used as clock or not. This information is
-   or not. This information is used by Verilator to mark the signal as
+   used by Verilator to mark the signal and any derrived signals as
-   clocker and propagate the clocker attribute automatically to derived
+   clocker.  See :vlopt:`--clk`.
-   signals. See :vlopt:`--clk`.
 
    Same as :option:`clocker` and :option:`no_clocker` in configuration
    files.