gen_vimdoc.py: support lua/shared.lua module [ci skip]

runtime/doc/if_lua.txt

@@ -30,7 +30,7 @@ finds and loads Lua modules.  The conventions are similar to VimL plugins,
 with some extra features.  See |lua-require-example| for a walkthrough.
 
 ==============================================================================
-Importing modules					*lua-require*
+Importing Lua modules					*lua-require*
 
 Nvim automatically adjusts `package.path` and `package.cpath` according to
 effective 'runtimepath' value.  Adjustment happens whenever 'runtimepath' is
@@ -325,9 +325,10 @@ Examples: >
 Note that currently second argument to `luaeval` undergoes VimL to lua 
 conversion, so changing containers in lua do not affect values in VimL. Return 
 value is also always converted. When converting, |msgpack-special-dict|s are 
+treated specially.
 
 ==============================================================================
-vim.*							*lua-vim* *lua-stdlib*
+Lua standard modules					*lua-stdlib*
 
 The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
 various functions and sub-modules.  It is always loaded, thus require("vim")
@@ -361,7 +362,7 @@ Note that underscore-prefixed functions (e.g. "_os_proc_children") are
 internal/private and must not be used by plugins.
 
 ------------------------------------------------------------------------------
-vim.api.* functions
+VIM.API							*lua-api*
 
 `vim.api` exposes the full Nvim |API| as a table of Lua functions.
 
@@ -371,7 +372,7 @@ For example, to use the "nvim_get_current_line()" API function, call
     print(tostring(vim.api.nvim_get_current_line()))
 
 ------------------------------------------------------------------------------
-vim.* builtin functions
+VIM							*lua-util*
 
 vim.inspect({object}, {options})                                 *vim.inspect*
 	Return a human-readable representation of the passed object. See
@@ -419,7 +420,7 @@ vim.types						*lua-vim.types*
 	only contain values for these three types.
 
 ==============================================================================
-Vim Lua Functions                                                    *lua-vim*
+Lua module: vim                                                      *lua-vim*
 
 gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
                 Split a string by a given separator. The separator can be a
@@ -442,11 +443,12 @@ gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
 split({s}, {sep}, {plain})                                       *vim.split()*
                 Split a string by a given separator.
 
-                Examples:
+                Examples: >
 
-                - split(":aa::b:", ":") returns {'','aa','','bb',''}
-                - split("axaby", "ab?") returns {'','x','y'}
-                - split(x*yz*o, "*", true) returns {'x','yz','o'}
+                  split(":aa::b:", ":")     --> {'','aa','','bb',''}
+                  split("axaby", "ab?")     --> {'','x','y'}
+                  split(x*yz*o, "*", true)  --> {'x','yz','o'}
+<
 
                 Parameters: ~
                     {s}      String The string to split
@@ -483,4 +485,24 @@ deepcopy({orig})                                              *vim.deepcopy()*
                     A new table where the keys and values are deepcopies of
                     the keys and values from the original table.
 
+
+
+
+tbl_contains({t}, {value})                                *vim.tbl_contains()*
+                TODO: Documentation
+
+tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
+                Parameters: ~
+                    {behavior}  Decides what to do if a key is found in more
+                                than one map:
+                                - "error": raise an error
+                                - "keep": use value from the leftmost map
+                                - "force": use value from the rightmost map
+
+                See also: ~
+                    |extend()|
+
+tbl_flatten({t})                                           *vim.tbl_flatten()*
+                TODO: Documentation
+
  vim:tw=78:ts=8:ft=help:norl:

runtime/lua/vim/shared.lua

@@ -16,14 +16,14 @@ local function tbl_contains(t, value)
   return false
 end
 
---- Merges two or more map-like tables.
+-- Merges two or more map-like tables.
 --
 --@see |extend()|
 --
--- behavior: Decides what to do if a key is found in more than one map:
---           "error": raise an error
---           "keep":  use value from the leftmost map
---           "force": use value from the rightmost map
+--@param behavior Decides what to do if a key is found in more than one map:
+---      - "error": raise an error
+---      - "keep":  use value from the leftmost map
+---      - "force": use value from the rightmost map
 local function tbl_extend(behavior, ...)
   if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then
     error('invalid "behavior": '..tostring(behavior))

scripts/gen_vimdoc.py

@@ -70,26 +70,41 @@ CONFIG = {
       'ui.c',
     ],
     # List of files/directories for doxygen to read, separated by blanks
-    'files': os.path.join(base_dir, 'src/nvim/api'), 
+    'files': os.path.join(base_dir, 'src/nvim/api'),
     # file patterns used by doxygen
     'file_patterns': '*.h *.c',
     # Only function with this prefix are considered
     'func_name_prefix': 'nvim_',
+    # Section name overrides.
+    'section_name': {
+        'vim.c': 'Global',
+    },
+    # Module name overrides (for Lua).
+    'module_override': {},
+    # Append the docs for these modules, do not start a new section.
+    'append_only' : [],
   },
   'lua': {
     'filename': 'if_lua.txt',
-    'section_start_token': '*vim-lua*',
+    'section_start_token': '*lua-vim*',
     'section_order' : [
       'vim.lua',
+      'shared.lua',
     ],
-    'files': os.path.join(base_dir, 'src/nvim/lua/vim.lua'), 
+    'files': ' '.join([
+        os.path.join(base_dir, 'src/nvim/lua/vim.lua'),
+        os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
+        ]),
     'file_patterns': '*.lua',
     'func_name_prefix': '',
-  }
-}
-# Section name overrides.
-section_name = {
-    'vim.c': 'Global',
+    'section_name': {},
+    'module_override': {
+        'shared': 'vim',  # `shared` functions are exposed on the `vim` module.
+    },
+    'append_only' : [
+      'shared.lua',
+    ],
+  },
 }
 
 param_exclude = (
@@ -303,7 +318,7 @@ def render_node(n, text, prefix='', indent='', width=62):
     elif n.nodeName == 'listitem':
         for c in n.childNodes:
             text += indent + prefix + render_node(c, text, indent=indent+(' ' * len(prefix)), width=width)
-    elif n.nodeName == 'para':
+    elif n.nodeName in ('para', 'heading'):
         for c in n.childNodes:
             text += render_node(c, text, indent=indent, width=width)
         if is_inline(n):
@@ -466,9 +481,10 @@ def parse_source_xml(filename, mode):
 
         if mode == 'lua':
             fstem = compoundname.split('.')[0]
-            vimtag = '*%s.%s()*' % (fstem, name)
+            fstem = CONFIG[mode]['module_override'].get(fstem, fstem)
+            vimtag = '*{}.{}()*'.format(fstem, name)
         else:
-            vimtag = '*%s()*' % name
+            vimtag = '*{}()*'.format(name)
 
         params = []
         type_length = 0
@@ -646,14 +662,14 @@ def gen_docs(config):
 
                     if doc:
                         filename = os.path.basename(filename)
-                        name = section_name.get(filename, name)
+                        name = CONFIG[mode]['section_name'].get(filename, name)
 
                         if mode == 'lua':
-                            title = '%s Lua Functions' % name
-                            helptag = '*%s-lua*' % name.lower()
+                            title = 'Lua module: {}'.format(name.lower())
+                            helptag = '*lua-{}*'.format(name.lower())
                         else:
-                            title = '%s Functions' % name
-                            helptag = '*api-%s*' % name.lower()
+                            title = '{} Functions'.format(name)
+                            helptag = '*api-{}*'.format(name.lower())
                         sections[filename] = (title, helptag, doc)
 
         if not sections:
@@ -664,23 +680,14 @@ def gen_docs(config):
         i = 0
         for filename in CONFIG[mode]['section_order']:
             if filename not in sections:
-                continue
+                raise RuntimeError('found new module "{}"; update the "section_order" map'.format(filename))
             title, helptag, section_doc = sections.pop(filename)
-
             i += 1
-            docs += sep
-            docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
-            docs += section_doc
-            docs += '\n\n\n'
-
-        if sections:
-            # In case new API sources are added without updating the order dict.
-            for title, helptag, section_doc in sections.values():
-                i += 1
+            if filename not in CONFIG[mode]['append_only']:
                 docs += sep
                 docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
-                docs += section_doc
-                docs += '\n\n\n'
+            docs += section_doc
+            docs += '\n\n\n'
 
         docs = docs.rstrip() + '\n\n'
         docs += ' vim:tw=78:ts=8:ft=help:norl:\n'

src/nvim/lua/vim.lua

@@ -203,12 +203,11 @@ end
 --- Split a string by a given separator.
 ---
 --- Examples:
----
----  * split(":aa::b:", ":") returns {'','aa','','bb',''}
----
----  * split("axaby", "ab?") returns {'','x','y'}
----
----  * split(x*yz*o, "*", true) returns {'x','yz','o'}
+--- <pre>
+---  split(":aa::b:", ":")     --> {'','aa','','bb',''}
+---  split("axaby", "ab?")     --> {'','x','y'}
+---  split(x*yz*o, "*", true)  --> {'x','yz','o'}
+--- </pre>
 ---
 --@param s String The string to split
 --@param sep String The separator to use (see |vim.gsplit()|)