build(gen_vimdoc): eliminate non-constant global variables (#17781)

1 files changed, 31 insertions, 42 deletions

diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 57b46a381e..755749cef6 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -79,13 +79,11 @@ LOG_LEVELS = {
     ]
 }
 
-fmt_vimhelp = False  # HACK
 text_width = 78
 script_path = os.path.abspath(__file__)
 base_dir = os.path.dirname(os.path.dirname(script_path))
 out_dir = os.path.join(base_dir, 'tmp-{target}-doc')
 filter_cmd = '%s %s' % (sys.executable, script_path)
-seen_funcs = set()
 msgs = []  # Messages to show on exit.
 lua2dox_filter = os.path.join(base_dir, 'scripts', 'lua2dox_filter')
 
@@ -287,11 +285,6 @@ annotation_map = {
 }
 
 
-# Tracks `xrefsect` titles.  As of this writing, used only for separating
-# deprecated functions.
-xrefs = set()
-
-
 # Raises an error with details about `o`, if `cond` is in object `o`,
 # or if `cond()` is callable and returns True.
 def debug_this(o, cond=True):
@@ -485,10 +478,8 @@ def update_params_map(parent, ret_map, width=62):
     return ret_map
 
 
-def render_node(n, text, prefix='', indent='', width=62):
+def render_node(n, text, prefix='', indent='', width=62, fmt_vimhelp=False):
     """Renders a node as Vim help text, recursively traversing all descendants."""
-    global fmt_vimhelp
-    global has_seen_preformatted
 
     def ind(s):
         return s if fmt_vimhelp else ''
@@ -566,7 +557,7 @@ def render_node(n, text, prefix='', indent='', width=62):
     return text
 
 
-def para_as_map(parent, indent='', width=62):
+def para_as_map(parent, indent='', width=62, fmt_vimhelp=False):
     """Extracts a Doxygen XML <para> node to a map.
 
     Keys:
@@ -599,7 +590,8 @@ def para_as_map(parent, indent='', width=62):
     last = ''
     if is_inline(parent):
         # Flatten inline text from a tree of non-block nodes.
-        text = doc_wrap(render_node(parent, ""), indent=indent, width=width)
+        text = doc_wrap(render_node(parent, "", fmt_vimhelp=fmt_vimhelp),
+                        indent=indent, width=width)
     else:
         prev = None  # Previous node
         for child in parent.childNodes:
@@ -615,7 +607,8 @@ def para_as_map(parent, indent='', width=62):
                 elif kind == 'see':
                     groups['seealso'].append(child)
                 elif kind in ('note', 'warning'):
-                    text += render_node(child, text, indent=indent, width=width)
+                    text += render_node(child, text, indent=indent,
+                                        width=width, fmt_vimhelp=fmt_vimhelp)
                 else:
                     raise RuntimeError('unhandled simplesect: {}\n{}'.format(
                         child.nodeName, child.toprettyxml(indent='  ', newl='\n')))
@@ -628,7 +621,8 @@ def para_as_map(parent, indent='', width=62):
                         and ' ' != text[-1]):
                     text += ' '
 
-                text += render_node(child, text, indent=indent, width=width)
+                text += render_node(child, text, indent=indent, width=width,
+                                    fmt_vimhelp=fmt_vimhelp)
                 prev = child
 
     chunks['text'] += text
@@ -639,10 +633,12 @@ def para_as_map(parent, indent='', width=62):
             update_params_map(child, ret_map=chunks['params'], width=width)
     for child in groups['return']:
         chunks['return'].append(render_node(
-            child, '', indent=indent, width=width))
+            child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp))
     for child in groups['seealso']:
         chunks['seealso'].append(render_node(
-            child, '', indent=indent, width=width))
+            child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp))
+
+    xrefs = set()
     for child in groups['xrefs']:
         # XXX: Add a space (or any char) to `title` here, otherwise xrefs
         # ("Deprecated" section) acts very weird...
@@ -652,10 +648,10 @@ def para_as_map(parent, indent='', width=62):
         chunks['xrefs'].append(doc_wrap(xrefdesc, prefix='{}: '.format(title),
                                         width=width) + '\n')
 
-    return chunks
+    return chunks, xrefs
 
 
-def fmt_node_as_vimhelp(parent, width=62, indent=''):
+def fmt_node_as_vimhelp(parent, width=62, indent='', fmt_vimhelp=False):
     """Renders (nested) Doxygen <para> nodes as Vim :help text.
 
     NB: Blank lines in a docstring manifest as <para> tags.
@@ -678,7 +674,7 @@ def fmt_node_as_vimhelp(parent, width=62, indent=''):
             return True
 
     for child in parent.childNodes:
-        para = para_as_map(child, indent, width)
+        para, _ = para_as_map(child, indent, width, fmt_vimhelp)
 
         # Generate text from the gathered items.
         chunks = [para['text']]
@@ -702,19 +698,16 @@ def fmt_node_as_vimhelp(parent, width=62, indent=''):
     return clean_lines('\n'.join(rendered_blocks).strip())
 
 
-def extract_from_xml(filename, target, width):
+def extract_from_xml(filename, target, width, fmt_vimhelp):
     """Extracts Doxygen info as maps without formatting the text.
 
     Returns two maps:
       1. Functions
       2. Deprecated functions
 
-    The `fmt_vimhelp` global controls some special cases for use by
+    The `fmt_vimhelp` variable controls some special cases for use by
     fmt_doxygen_xml_as_vimhelp(). (TODO: ugly :)
     """
-    global xrefs
-    global fmt_vimhelp
-    xrefs.clear()
     fns = {}  # Map of func_name:docstring.
     deprecated_fns = {}  # Map of func_name:docstring.
 
@@ -821,16 +814,22 @@ def extract_from_xml(filename, target, width):
                 signature = prefix + suffix
                 signature += vimtag.rjust(width - len(signature))
 
+        # Tracks `xrefsect` titles.  As of this writing, used only for separating
+        # deprecated functions.
+        xrefs_all = set()
         paras = []
         brief_desc = find_first(member, 'briefdescription')
         if brief_desc:
             for child in brief_desc.childNodes:
-                paras.append(para_as_map(child))
+                para, xrefs = para_as_map(child)
+                xrefs_all.update(xrefs)
 
         desc = find_first(member, 'detaileddescription')
         if desc:
             for child in desc.childNodes:
-                paras.append(para_as_map(child))
+                para, xrefs = para_as_map(child)
+                paras.append(para)
+                xrefs_all.update(xrefs)
             log.debug(
                 textwrap.indent(
                     re.sub(r'\n\s*\n+', '\n',
@@ -846,7 +845,6 @@ def extract_from_xml(filename, target, width):
             'seealso': [],
         }
         if fmt_vimhelp:
-            # HACK :(
             fn['desc_node'] = desc
             fn['brief_desc_node'] = brief_desc
 
@@ -865,18 +863,16 @@ def extract_from_xml(filename, target, width):
         if INCLUDE_C_DECL:
             fn['c_decl'] = c_decl
 
-        if 'Deprecated' in str(xrefs):
+        if 'Deprecated' in str(xrefs_all):
             deprecated_fns[name] = fn
         elif name.startswith(CONFIG[target]['fn_name_prefix']):
             fns[name] = fn
 
-        xrefs.clear()
-
     fns = collections.OrderedDict(sorted(
         fns.items(),
         key=lambda key_item_tuple: key_item_tuple[0].lower()))
     deprecated_fns = collections.OrderedDict(sorted(deprecated_fns.items()))
-    return (fns, deprecated_fns)
+    return fns, deprecated_fns
 
 
 def fmt_doxygen_xml_as_vimhelp(filename, target):
@@ -886,16 +882,14 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
       1. Vim help text for functions found in `filename`.
       2. Vim help text for deprecated functions.
     """
-    global fmt_vimhelp
-    fmt_vimhelp = True
     fns_txt = {}  # Map of func_name:vim-help-text.
     deprecated_fns_txt = {}  # Map of func_name:vim-help-text.
-    fns, _ = extract_from_xml(filename, target, width=text_width)
+    fns, _ = extract_from_xml(filename, target, text_width, True)
 
     for name, fn in fns.items():
         # Generate Vim :help for parameters.
         if fn['desc_node']:
-            doc = fmt_node_as_vimhelp(fn['desc_node'])
+            doc = fmt_node_as_vimhelp(fn['desc_node'], fmt_vimhelp=True)
         if not doc and fn['brief_desc_node']:
             doc = fmt_node_as_vimhelp(fn['brief_desc_node'])
         if not doc:
@@ -948,14 +942,9 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
 
         func_doc = "\n".join(split_lines)
 
-        if 'Deprecated' in xrefs:
-            deprecated_fns_txt[name] = func_doc
-        elif name.startswith(CONFIG[target]['fn_name_prefix']):
+        if name.startswith(CONFIG[target]['fn_name_prefix']):
             fns_txt[name] = func_doc
 
-        xrefs.clear()
-
-    fmt_vimhelp = False
     return ('\n\n'.join(list(fns_txt.values())),
             '\n\n'.join(list(deprecated_fns_txt.values())))
 
@@ -1059,7 +1048,7 @@ def main(config, args):
                 xmlfile = os.path.join(base,
                                        '{}.xml'.format(compound.getAttribute('refid')))
                 # Extract unformatted (*.mpack).
-                fn_map, _ = extract_from_xml(xmlfile, target, width=9999)
+                fn_map, _ = extract_from_xml(xmlfile, target, 9999, False)
                 # Extract formatted (:help).
                 functions_text, deprecated_text = fmt_doxygen_xml_as_vimhelp(
                     os.path.join(base, '{}.xml'.format(