From be74807eef13ff8c90d55cf8b22b01d6d33b1641 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 18 Jul 2023 15:42:30 +0100 Subject: docs(lua): more improvements (#24387) * docs(lua): teach lua2dox how to table * docs(lua): teach gen_vimdoc.py about local functions No more need to mark local functions with @private * docs(lua): mention @nodoc and @meta in dev-lua-doc * fixup! Co-authored-by: Justin M. Keyes --------- Co-authored-by: Justin M. Keyes --- scripts/gen_vimdoc.py | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) (limited to 'scripts/gen_vimdoc.py') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 0a7dd6e9ab..dfad1f000c 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -135,7 +135,7 @@ CONFIG = { # Section helptag. 'helptag_fmt': lambda name: f'*api-{name.lower()}*', # Per-function helptag. - 'fn_helptag_fmt': lambda fstem, name: f'*{name}()*', + 'fn_helptag_fmt': lambda fstem, name, istbl: f'*{name}()*', # Module name overrides (for Lua). 'module_override': {}, # Append the docs for these modules, do not start a new section. @@ -193,6 +193,7 @@ CONFIG = { 'fn_name_fmt': lambda fstem, name: ( name if fstem in [ 'vim.iter' ] else f'vim.{name}' if fstem in [ '_editor', 'vim.regex'] else + f'vim.{name}' if fstem == '_options' and not name[0].isupper() else f'{fstem}.{name}' if fstem.startswith('vim') else name ), @@ -210,14 +211,15 @@ CONFIG = { '*lua-vim*' if name.lower() == '_editor' else '*lua-vimscript*' if name.lower() == '_options' else f'*vim.{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( + 'fn_helptag_fmt': lambda fstem, name, istbl: ( f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else # Exclude fstem for methods f'*{name}()*' if ':' in name else f'*vim.{name}()*' if fstem.lower() == '_editor' else + f'*vim.{name}*' if fstem.lower() == '_options' and istbl else # Prevents vim.regex.regex f'*{fstem}()*' if fstem.endswith('.' + name) else - f'*{fstem}.{name}()*' + f'*{fstem}.{name}{"" if istbl else "()"}*' ), 'module_override': { # `shared` functions are exposed on the `vim` module. @@ -275,14 +277,11 @@ CONFIG = { '*lsp-core*' if name.lower() == 'lsp' else f'*lsp-{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( - f'*vim.lsp.{name}()*' - if fstem == 'lsp' and name != 'client' - else ( - '*vim.lsp.client*' - # HACK. TODO(justinmk): class/structure support in lua2dox - if 'lsp.client' == f'{fstem}.{name}' - else f'*vim.lsp.{fstem}.{name}()*')), + 'fn_helptag_fmt': lambda fstem, name, istbl: ( + f'*vim.lsp.{name}{"" if istbl else "()"}*' if fstem == 'lsp' and name != 'client' else + # HACK. TODO(justinmk): class/structure support in lua2dox + '*vim.lsp.client*' if 'lsp.client' == f'{fstem}.{name}' else + f'*vim.lsp.{fstem}.{name}{"" if istbl else "()"}*'), 'module_override': {}, 'append_only': [], }, @@ -295,10 +294,11 @@ CONFIG = { 'files': ['runtime/lua/vim/diagnostic.lua'], 'file_patterns': '*.lua', 'fn_name_prefix': '', + 'include_tables': False, 'section_name': {'diagnostic.lua': 'diagnostic'}, 'section_fmt': lambda _: 'Lua module: vim.diagnostic', 'helptag_fmt': lambda _: '*diagnostic-api*', - 'fn_helptag_fmt': lambda fstem, name: f'*vim.{fstem}.{name}()*', + 'fn_helptag_fmt': lambda fstem, name, istbl: f'*vim.{fstem}.{name}{"" if istbl else "()"}*', 'module_override': {}, 'append_only': [], }, @@ -328,7 +328,7 @@ CONFIG = { '*lua-treesitter-core*' if name.lower() == 'treesitter' else f'*lua-treesitter-{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( + 'fn_helptag_fmt': lambda fstem, name, istbl: ( f'*vim.{fstem}.{name}()*' if fstem == 'treesitter' else f'*{name}()*' @@ -842,6 +842,13 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): if return_type == '': continue + if 'local_function' in return_type: # Special from lua2dox.lua. + continue + + istbl = return_type.startswith('table') # Special from lua2dox.lua. + if istbl and not CONFIG[target].get('include_tables', True): + continue + if return_type.startswith(('ArrayOf', 'DictionaryOf')): parts = return_type.strip('_').split('_') return_type = '{}({})'.format(parts[0], ', '.join(parts[1:])) @@ -904,15 +911,20 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): if '.' in compoundname: fstem = compoundname.split('.')[0] fstem = CONFIG[target]['module_override'].get(fstem, fstem) - vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name) + vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name, istbl) if 'fn_name_fmt' in CONFIG[target]: name = CONFIG[target]['fn_name_fmt'](fstem, name) - prefix = '%s(' % name - suffix = '%s)' % ', '.join('{%s}' % a[1] for a in params - if a[0] not in ('void', 'Error', 'Arena', - 'lua_State')) + if istbl: + aopen, aclose = '', '' + else: + aopen, aclose = '(', ')' + + prefix = name + aopen + suffix = ', '.join('{%s}' % a[1] for a in params + if a[0] not in ('void', 'Error', 'Arena', + 'lua_State')) + aclose if not fmt_vimhelp: c_decl = '%s %s(%s);' % (return_type, name, ', '.join(c_args)) -- cgit