Commentary

bin/verilator

@@ -628,7 +628,7 @@ large and not desired.
 =item --dump-treei <level>
 
 Rarely needed.  Enable writing .tree debug files with a specific dumping
-level, 0 disbles dumps and is equivelent to "--no-dump-tree".  Level 9
+level, 0 disbles dumps and is equivalent to "--no-dump-tree".  Level 9
 enables dumping of every stage.
 
 =item -E
@@ -921,7 +921,7 @@ break the loop.
 In addition produces a GraphViz DOT file of the entire strongly connected
 components within the source associated with each loop. This is produced
 irrespective of whether --dump-tree is set. Such graphs may help in
-analysing the problem, but can be very large indeed.
+analyzing the problem, but can be very large indeed.
 
 Various commands exist for viewing and manipulating DOT files. For example
 the I<dot> command can be used to convert a DOT file to a PDF for
@@ -1187,7 +1187,7 @@ so the above C<always> block would not trigger.
 
 While it is not good practice, there are some designs that rely on X
 E<rarr> 0 triggering a C<negedge>, particularly in reset sequences. Using
---x-initial-edge with Verilator will replicate this behaviour. It will also
+--x-initial-edge with Verilator will replicate this behavior. It will also
 ensure that X E<rarr> 1 triggers a C<posedge>.
 
 B<Note.> Some users have reported that using this option can affect
@@ -1972,7 +1972,7 @@ please file a bug if a feature you need is missing.
 
 Verilator implements a very small subset of Verilog AMS (Verilog Analog and
 Mixed-Signal Extensions) with the subset corresponding to those VMS
-keywords with near equivelents in the Verilog 2005 or SystemVerilog 2009
+keywords with near equivalents in the Verilog 2005 or SystemVerilog 2009
 languages.
 
 AMS parsing is enabled with "--language VAMS" or "--language 1800+VAMS".
@@ -2432,7 +2432,7 @@ reset works.  (Note this is what the hardware will really do.)  In
 practice, just setting all variables to one at startup finds most problems.
 
 B<Note.> --x-assign applies to variables explicitly initialized or assigned to
-X. Unititialized clocks are initialized to zero, while all other state holding
+X. Uninitialized clocks are initialized to zero, while all other state holding
 variables are initialized to a random value.
 
 Event driven simulators will generally trigger an edge on a transition from X

internals.pod

@@ -341,6 +341,37 @@ C<op4p> in turn.
 
 =back
 
+=head3 Caution on Using Iterators When Child Changes
+
+Visitors often replace one node with another node; V3Width and V3Const are
+major examples.  A visitor which is the parent of such a replacement needs
+to be aware that calling iteration may cause the children to change.  For
+example:
+
+    // nodep->lhsp() is 0x1234000
+    nodep->lhsp()->iterateAndNext(...);  // and under covers nodep->lhsp() changes
+    // nodep->lhsp() is 0x5678400
+    nodep->lhsp()->iterateAndNext(...);
+
+Will work fine, as even if the first iterate causes a new node to take the
+place of the lhsp(), that edit will update nodep->lhsp() and the second
+call will correctly see the change. Alternatively:
+
+    lp = nodep->lhsp();
+    // nodep->lhsp() is 0x1234000, lp is 0x1234000
+    lp->iterateAndNext(...); **lhsp=NULL;** // and under covers nodep->lhsp() changes
+    // nodep->lhsp() is 0x5678400, lp is 0x1234000
+    lp->iterateAndNext(...);
+
+This will cause bugs or a core dump, as lp is a dangling pointer.  Thus it
+is advisable to set lhsp=NULL shown in the *'s above to make sure these
+dangles are avoided.  Another alternative used in special cases mostly in
+V3Width is to use acceptSubtreeReturnEdits, which operates on a single node
+and returns the new pointer if any.  Note acceptSubtreeReturnEdits does not
+follow nextp() links.
+
+    lp = lp->acceptSubtreeReturnEdits()
+
 =head2 Identifying derived classes
 
 A common requirement is to identify the specific C<AstNode> class we are
@@ -372,7 +403,7 @@ Verilator primary manual.
 It is important to add tests for failures as well as success (for example to
 check that an error message is correctly triggered).
 
-Tests that fail should by convenition have the suffix C<_bad> in their name,
+Tests that fail should by convention have the suffix C<_bad> in their name,
 and include C<fails =E<gt> 1> in either their C<compile> or C<execute> step as
 appropriate.
 
@@ -388,7 +419,7 @@ For convenience, a summary of the most commonly used features is provided
 here. All drivers require a call to C<compile> subroutine to compile the
 test. For run-time tests, this is followed by a call to the C<execute>
 subroutine. Both of these functions can optionally be provided with a hash
-table as argument specifying additonal options.
+table as argument specifying additional options.
 
 The test driver assumes by default that the source Verilog file name
 matches the PERL driver name. So a test whose driver is C<t/t_mytest.pl>
@@ -608,8 +639,8 @@ Shows the value of the node's user1p...user5p, if non-NULL.
 Many nodes have an explicit data type.  "@dt=0x..." indicates the address
 of the data type (AstNodeDType) this node uses.
 
-If a data type is present and is numberic, it then prints the width of the
-item. This field is a squence of flag characters and width data as follows:
+If a data type is present and is numeric, it then prints the width of the
+item. This field is a sequence of flag characters and width data as follows:
 
 C<s> if the node is signed.