From a54f88ea64c02f9fa7bf3d7445cdaaea424d439f Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 17 Jul 2023 10:39:52 +0100 Subject: docs(lua): do not render self args --- scripts/gen_vimdoc.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 8ad6442f3b..6ca330ae22 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -45,6 +45,7 @@ import logging from pathlib import Path from xml.dom import minidom +Element = minidom.Element MIN_PYTHON_VERSION = (3, 6) MIN_DOXYGEN_VERSION = (1, 9, 0) @@ -720,8 +721,7 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F return chunks, xrefs - -def fmt_node_as_vimhelp(parent, width=text_width - indentation, indent='', +def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent='', fmt_vimhelp=False): """Renders (nested) Doxygen nodes as Vim :help text. @@ -734,6 +734,8 @@ def fmt_node_as_vimhelp(parent, width=text_width - indentation, indent='', max_name_len = max_name(m.keys()) + 4 out = '' for name, desc in m.items(): + if name == 'self': + continue name = ' • {}'.format('{{{}}}'.format(name).ljust(max_name_len)) out += '{}{}\n'.format(name, desc) return out.rstrip() @@ -851,6 +853,7 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): and any(x[1] == 'self' for x in params): split_return = return_type.split(' ') name = f'{split_return[1]}:{name}' + params = [x for x in params if x[1] != 'self'] c_args = [] for param_type, param_name in params: -- cgit From 3fd504dbec39eeced1bea17d9f3bd06de7f3e4d8 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Sun, 16 Jul 2023 09:34:50 +0100 Subject: docs: handle whitespace in emmycomments --- scripts/lua2dox.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua index bb5214f091..b0eb4c086c 100644 --- a/scripts/lua2dox.lua +++ b/scripts/lua2dox.lua @@ -328,6 +328,7 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename) line = string_trim(inStream:getLine()) l = l + 1 if string.sub(line, 1, 2) == '--' then -- it's a comment + line = line:gsub('^---%s+@', '---@') -- Allow people to write style similar to EmmyLua (since they are basically the same) -- instead of silently skipping things that start with --- if string.sub(line, 3, 3) == '@' then -- it's a magic comment @@ -341,6 +342,7 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename) if vim.startswith(line, '---@cast') or vim.startswith(line, '---@diagnostic') or vim.startswith(line, '---@overload') + or vim.startswith(line, '---@meta') or vim.startswith(line, '---@type') then -- Ignore LSP directives outStream:writeln('// gg:"' .. line .. '"') -- cgit From 0ac3c4d6314df5fe40571a83e157a425ab7ce16d Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Sat, 15 Jul 2023 16:55:32 +0100 Subject: docs(lua): move function docs to lua files --- scripts/gen_vimdoc.py | 61 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 11 deletions(-) (limited to 'scripts') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 6ca330ae22..eacf4dc24d 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -144,6 +144,14 @@ CONFIG = { 'mode': 'lua', 'filename': 'lua.txt', 'section_order': [ + 'highlight.lua', + 'regex.lua', + 'diff.lua', + 'mpack.lua', + 'json.lua', + 'spell.lua', + 'builtin.lua', + '_options.lua', '_editor.lua', '_inspector.lua', 'shared.lua', @@ -160,6 +168,7 @@ CONFIG = { 'files': [ 'runtime/lua/vim/iter.lua', 'runtime/lua/vim/_editor.lua', + 'runtime/lua/vim/_options.lua', 'runtime/lua/vim/shared.lua', 'runtime/lua/vim/loader.lua', 'runtime/lua/vim/uri.lua', @@ -167,30 +176,48 @@ CONFIG = { 'runtime/lua/vim/filetype.lua', 'runtime/lua/vim/keymap.lua', 'runtime/lua/vim/fs.lua', + 'runtime/lua/vim/highlight.lua', 'runtime/lua/vim/secure.lua', 'runtime/lua/vim/version.lua', 'runtime/lua/vim/_inspector.lua', + 'runtime/lua/vim/_meta/builtin.lua', + 'runtime/lua/vim/_meta/diff.lua', + 'runtime/lua/vim/_meta/mpack.lua', + 'runtime/lua/vim/_meta/json.lua', + 'runtime/lua/vim/_meta/regex.lua', + 'runtime/lua/vim/_meta/spell.lua', ], 'file_patterns': '*.lua', 'fn_name_prefix': '', + 'fn_name_fmt': lambda fstem, name: ( + name if fstem in [ 'vim.iter' ] else + f'vim.{name}' if fstem in [ '_editor', 'vim.regex'] else + f'{fstem}.{name}' if fstem.startswith('vim') else + name + ), 'section_name': { 'lsp.lua': 'core', '_inspector.lua': 'inspector', }, 'section_fmt': lambda name: ( - 'Lua module: vim' - if name.lower() == '_editor' - else f'Lua module: {name.lower()}'), + 'Lua module: vim' if name.lower() == '_editor' else + 'LUA-VIMSCRIPT BRIDGE' if name.lower() == '_options' else + f'VIM.{name.upper()}' if name.lower() in [ 'highlight', 'mpack', 'json', 'diff', 'spell', 'regex' ] else + 'VIM' if name.lower() == 'builtin' else + f'Lua module: vim.{name.lower()}'), 'helptag_fmt': lambda name: ( - '*lua-vim*' - if name.lower() == '_editor' - else f'*lua-{name.lower()}*'), + '*lua-vim*' if name.lower() == '_editor' else + '*lua-vimscript*' if name.lower() == '_options' else + f'*lua-{name.lower()}*'), 'fn_helptag_fmt': lambda fstem, name: ( - f'*vim.{name}()*' - if fstem.lower() == '_editor' - else f'*{name}()*' - if name[0].isupper() - else f'*{fstem}.{name}()*'), + 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 + # Prevents vim.regex.regex + f'*{fstem}()*' if fstem.endswith('.' + name) else + f'*{fstem}.{name}()*' + ), 'module_override': { # `shared` functions are exposed on the `vim` module. 'shared': 'vim', @@ -201,9 +228,16 @@ CONFIG = { 'filetype': 'vim.filetype', 'keymap': 'vim.keymap', 'fs': 'vim.fs', + 'highlight': 'vim.highlight', 'secure': 'vim.secure', 'version': 'vim.version', 'iter': 'vim.iter', + 'diff': 'vim', + 'builtin': 'vim', + 'mpack': 'vim.mpack', + 'json': 'vim.json', + 'regex': 'vim.regex', + 'spell': 'vim.spell', }, 'append_only': [ 'shared.lua', @@ -542,6 +576,8 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation, text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1]) elif o[0:4] == 'vim\n': text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1]) + elif o[0:5] == 'help\n': + text += o[4:-1] else: text += '>{}{}\n<'.format(ensure_nl, o) @@ -869,6 +905,9 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): fstem = CONFIG[target]['module_override'].get(fstem, fstem) vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name) + 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', -- cgit From c2d7c2826ca77b0ca31bec511fdcdf1e4abaf946 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 17 Jul 2023 15:13:54 +0100 Subject: docs(lua): change *lua-foo* -> *vim.foo* --- scripts/gen_vimdoc.py | 6 +++++- scripts/lua2dox.lua | 5 +++++ 2 files changed, 10 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index eacf4dc24d..984939a692 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -208,7 +208,7 @@ CONFIG = { 'helptag_fmt': lambda name: ( '*lua-vim*' if name.lower() == '_editor' else '*lua-vimscript*' if name.lower() == '_options' else - f'*lua-{name.lower()}*'), + f'*vim.{name.lower()}*'), 'fn_helptag_fmt': lambda fstem, name: ( f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else # Exclude fstem for methods @@ -1160,6 +1160,10 @@ def main(doxygen_config, args): if doc: doc_list.append(doc) + # Can't use '.' in @defgroup, so convert to '--' + # "vim.json" => "vim-dot-json" + groupname = groupname.replace('-dot-', '.') + section_docs[groupname] = "\n".join(doc_list) # Generate docs for all functions in the current module. diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua index b0eb4c086c..3f0d0505dd 100644 --- a/scripts/lua2dox.lua +++ b/scripts/lua2dox.lua @@ -416,6 +416,11 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename) magic = table.concat(magic_split, ' ') + if magic_split[1] == 'defgroup' or magic_split[1] == 'addtogroup' then + -- Can't use '.' in defgroup, so convert to '--' + magic = magic:gsub('%.', '-dot-') + end + outStream:writeln('/// @' .. magic) fn_magic = checkComment4fn(fn_magic, magic) end -- cgit From e6e0bc225b14f135e2270f3bacd5fb8ebf7e3792 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 17 Jul 2023 15:22:44 +0100 Subject: refactor(gen_vimdoc): put defgroup handling in a function --- scripts/gen_vimdoc.py | 68 ++++++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 30 deletions(-) (limited to 'scripts') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 984939a692..0a7dd6e9ab 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -46,6 +46,7 @@ from pathlib import Path from xml.dom import minidom Element = minidom.Element +Document = minidom.Document MIN_PYTHON_VERSION = (3, 6) MIN_DOXYGEN_VERSION = (1, 9, 0) @@ -1089,6 +1090,42 @@ def delete_lines_below(filename, tokenstr): fp.writelines(lines[0:i]) +def extract_defgroups(base: str, dom: Document): + '''Generate module-level (section) docs (@defgroup).''' + section_docs = {} + + for compound in dom.getElementsByTagName('compound'): + if compound.getAttribute('kind') != 'group': + continue + + # Doxygen "@defgroup" directive. + groupname = get_text(find_first(compound, 'name')) + groupxml = os.path.join(base, '%s.xml' % + compound.getAttribute('refid')) + + group_parsed = minidom.parse(groupxml) + doc_list = [] + brief_desc = find_first(group_parsed, 'briefdescription') + if brief_desc: + for child in brief_desc.childNodes: + doc_list.append(fmt_node_as_vimhelp(child)) + + desc = find_first(group_parsed, 'detaileddescription') + if desc: + doc = fmt_node_as_vimhelp(desc) + + if doc: + doc_list.append(doc) + + # Can't use '.' in @defgroup, so convert to '--' + # "vim.json" => "vim-dot-json" + groupname = groupname.replace('-dot-', '.') + + section_docs[groupname] = "\n".join(doc_list) + + return section_docs + + def main(doxygen_config, args): """Generates: @@ -1130,41 +1167,12 @@ def main(doxygen_config, args): fn_map_full = {} # Collects all functions as each module is processed. sections = {} - section_docs = {} sep = '=' * text_width base = os.path.join(output_dir, 'xml') dom = minidom.parse(os.path.join(base, 'index.xml')) - # Generate module-level (section) docs (@defgroup). - for compound in dom.getElementsByTagName('compound'): - if compound.getAttribute('kind') != 'group': - continue - - # Doxygen "@defgroup" directive. - groupname = get_text(find_first(compound, 'name')) - groupxml = os.path.join(base, '%s.xml' % - compound.getAttribute('refid')) - - group_parsed = minidom.parse(groupxml) - doc_list = [] - brief_desc = find_first(group_parsed, 'briefdescription') - if brief_desc: - for child in brief_desc.childNodes: - doc_list.append(fmt_node_as_vimhelp(child)) - - desc = find_first(group_parsed, 'detaileddescription') - if desc: - doc = fmt_node_as_vimhelp(desc) - - if doc: - doc_list.append(doc) - - # Can't use '.' in @defgroup, so convert to '--' - # "vim.json" => "vim-dot-json" - groupname = groupname.replace('-dot-', '.') - - section_docs[groupname] = "\n".join(doc_list) + section_docs = extract_defgroups(base, dom) # Generate docs for all functions in the current module. for compound in dom.getElementsByTagName('compound'): -- cgit From 6e9b204afbe5f16c44a2697aed07aafff36bf856 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 17 Jul 2023 16:39:57 +0100 Subject: fix: doc errors --- scripts/lua2dox.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua index 3f0d0505dd..55cb566ca3 100644 --- a/scripts/lua2dox.lua +++ b/scripts/lua2dox.lua @@ -363,6 +363,8 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename) magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1') magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1') end + -- handle the return of vim.spell.check + magic = magic:gsub('({.*}%[%])', '`%1`') magic_split = string_split(magic, ' ') end -- cgit