halcompile: man pages give array ranges as 00..size-1

Pins and params of an array sized by an expression were documented as
00..personality; the last index is personality-1. Expressions that are
not a plain name are bracketed: 00..(personality & 0xff)-1. Affects the
man pages of bitmerge, bitslice, carousel, demux, gantry, limit_axis,
lincurve, logic, max31855, moveoff, multiswitch, output_buffer and
radiobutton.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: tzuohann

src/hal/utils/halcompile.g

@@ -1081,6 +1081,26 @@ def to_hal_man(s):
     s = re.sub("#+", lambda m: "__" + "M" * len(m.group(0)) + "__", s)
     return s
 
+def wraps(s):
+    """True when the first '(' of s closes at its last character."""
+    depth = 0
+    for i, ch in enumerate(s):
+        depth += {'(': 1, ')': -1}.get(ch, 0)
+        if depth == 0:
+            return i == len(s) - 1
+    return False
+
+def last_index(size):
+    """The highest index of a pin/param array whose size is the expression
+    `size`: arrays run 00..size-1 (issue #3519). An expression that is not a
+    plain name is bracketed so the -1 applies to all of it."""
+    size = str(size).strip()
+    while size.startswith('(') and size.endswith(')') and wraps(size):
+        size = size[1:-1].strip()
+    if not re.match(r'^\w+$', size):
+        size = '(%s)' % size
+    return '%s-1' % size
+
 # Generate an adoc file from the embedded declarations, defines and
 # documentation.
 def document(filename, outfilebase):
@@ -1195,7 +1215,7 @@ def document(filename, outfilebase):
         if array:
             sz = name.count("#")
             if isinstance(array, tuple):
-                print(" (%s=%0*d..%s)" % ("M" * sz, sz, 0, array[1]), end=' ', file=f)
+                print(" (%s=%0*d..%s)" % ("M" * sz, sz, 0, last_index(array[1])), end=' ', file=f)
             else:
                 print(" (%s=%0*d..%0*d)" % ("M" * sz, sz, 0, sz, array-1), end=' ', file=f)
         if personality:
@@ -1218,7 +1238,7 @@ def document(filename, outfilebase):
             if array:
                 sz = name.count("#")
                 if isinstance(array, tuple):
-                    print(" (%s=%0*d..%s)" % ("M" * sz, sz, 0, array[1]), end=' ', file=f)
+                    print(" (%s=%0*d..%s)" % ("M" * sz, sz, 0, last_index(array[1])), end=' ', file=f)
                 else:
                     print(" (%s=%0*d..%0*d)" % ("M" * sz, sz, 0, sz, array-1), end=' ', file=f)
             if personality: