Merge pull request #3891 from grandixximo/issue-3880-fix

Clarify o-code numbering and scoping rules in docs

Author: andypugh

docs/src/gcode/o-code.adoc

@@ -24,14 +24,28 @@ For example 'o100' is easier to see than 'O100' that it is not a '0'.
 
 == Numbering
 
-Numbered o-codes must have a unique number for each subroutine,
+There are two categories of o-codes with different scoping rules:
+
+*Subroutine definitions* (`sub`/`endsub`, `call`) are *global*.
+Each subroutine must have a unique number or name across the entire program
+and all called files.
+
+*Control flow* (`if`/`endif`, `while`/`endwhile`, `do`/`while`,
+`repeat`/`endrepeat`, `break`, `continue`) are *local* to the subroutine
+or main program where they appear.  The interpreter automatically scopes them,
+so `o100 if` inside `o<helper>` does not conflict with `o100 if` in the main
+program or in any other subroutine.  You can safely reuse the same o-numbers
+for control flow in different subroutines.
+
+Within a single subroutine body (or the main program), each o-number should
+still be used for only one control flow block.
 
 .Numbering Example
 [source,{ngc}]
 ----
 (the start of o100)
 o100 sub
-(notice that the if-endif block uses a different number)
+(notice that the if-endif block uses a different number within this sub)
   (the start of o110)
   o110 if [#2 GT 5]
     (some code here)
@@ -42,6 +56,26 @@ o100 sub
 o100 endsub
 ----
 
+.Reusing Control Flow Numbers Across Subroutines (valid)
+[source,{ngc}]
+----
+(o100 if in helper.ngc does not conflict with o100 if in another.ngc)
+
+(file: helper.ngc)
+o<helper> sub
+  o100 if [#1 GT 5]
+    (do something)
+  o100 endif
+o<helper> endsub
+
+(file: another.ngc)
+o<another> sub
+  o100 if [#1 LT 0]
+    (do something else)
+  o100 endif
+o<another> endsub
+----
+
 [[ocode:comments]]
 == Comments(((Comments)))
 
@@ -50,7 +84,8 @@ change in the future.
 
 The behavior is undefined if:
 
-* The same number is used for more than one block.
+* The same number is used for more than one block within the same scope
+  (see <<Numbering>> for scoping rules).
 * Other words are used on a line with an o-word.
 * Comments are used on a line with an o-word.