From 7984959ef521bd06332d67a27b6b2ea07ffea43f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 6 Nov 2017 03:59:34 +0100 Subject: gen_api_vimdoc.py: support Doxygen @note --- scripts/gen_api_vimdoc.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'scripts/gen_api_vimdoc.py') diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py index 4dcb42d685..9128483f5f 100644 --- a/scripts/gen_api_vimdoc.py +++ b/scripts/gen_api_vimdoc.py @@ -217,7 +217,12 @@ def parse_para(parent, width=62): width=width) + '\n') elif child.nodeName == 'simplesect': kind = child.getAttribute('kind') - if kind == 'return': + if kind == 'note': + lines.append('Note:') + lines.append(doc_wrap(parse_para(child), + prefix=' ', + width=width)) + elif kind == 'return': lines.append('%s:~' % kind.title()) lines.append(doc_wrap(parse_para(child), prefix=' ', -- cgit From 7e59b897c150e4d43af223aa47da115ee8beb653 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 6 Nov 2017 04:15:43 +0100 Subject: gen_api_vimdoc.py: workaround: attributes of (void) functions --- scripts/gen_api_vimdoc.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'scripts/gen_api_vimdoc.py') diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py index 9128483f5f..8bc32d938f 100644 --- a/scripts/gen_api_vimdoc.py +++ b/scripts/gen_api_vimdoc.py @@ -38,6 +38,10 @@ import subprocess from xml.dom import minidom +if sys.version_info[0] < 3: + print("use Python 3") + sys.exit(1) + doc_filename = 'api.txt' # String used to find the start of the generated part of the doc. section_start_token = '*api-global*' @@ -285,14 +289,19 @@ def parse_source_xml(filename): parts = return_type.strip('_').split('_') return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:])) + name = get_text(get_child(member, 'name')) + annotations = get_text(get_child(member, 'argsstring')) if annotations and ')' in annotations: annotations = annotations.rsplit(')', 1)[-1].strip() + # XXX: (doxygen 1.8.11) 'argsstring' only includes FUNC_ATTR_* + # attributes if the function signature is non-void. + # Force attributes here for such functions. + if name == 'nvim_get_mode' and len(annotations) == 0: + annotations += 'FUNC_API_ASYNC' annotations = filter(None, map(lambda x: annotation_map.get(x), annotations.split())) - name = get_text(get_child(member, 'name')) - vimtag = '*%s()*' % name args = [] type_length = 0 -- cgit From 280943d9b938e95fcf77ef5290576630b84511fb Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 6 Nov 2017 02:00:39 +0100 Subject: doc: API (generated) --- scripts/gen_api_vimdoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/gen_api_vimdoc.py') diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py index 8bc32d938f..51e585a007 100644 --- a/scripts/gen_api_vimdoc.py +++ b/scripts/gen_api_vimdoc.py @@ -73,7 +73,7 @@ text_width = 78 script_path = os.path.abspath(__file__) base_dir = os.path.dirname(os.path.dirname(script_path)) src_dir = os.path.join(base_dir, 'src/nvim/api') -out_dir = os.path.join(base_dir, 'tmp/api_doc') +out_dir = os.path.join(base_dir, 'tmp-api-doc') filter_cmd = '%s %s' % (sys.executable, script_path) seen_funcs = set() -- cgit From 9ada97a81027e03d4988cc61b366ff05e2e5b92f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Dec 2017 01:30:05 +0100 Subject: gen_api_vimdoc.py: require "nvim_" prefix Avoids doxygen bugs (things that aren't functions) and other noise (e.g. `remote_ui_disconnect()` was incorrectly included in api.txt). --- scripts/gen_api_vimdoc.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'scripts/gen_api_vimdoc.py') diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py index 51e585a007..4ddf415f1a 100644 --- a/scripts/gen_api_vimdoc.py +++ b/scripts/gen_api_vimdoc.py @@ -45,6 +45,8 @@ if sys.version_info[0] < 3: doc_filename = 'api.txt' # String used to find the start of the generated part of the doc. section_start_token = '*api-global*' +# Required prefix for API function names. +api_func_name_prefix = 'nvim_' # Section name overrides. section_name = { @@ -260,11 +262,11 @@ def parse_parblock(parent, width=62): def parse_source_xml(filename): """Collects API functions. - This returns two strings: - 1. The API functions - 2. The deprecated API functions + Returns two strings: + 1. API functions + 2. Deprecated API functions - The caller decides what to do with the deprecated documentation. + Caller decides what to do with the deprecated documentation. """ global xrefs xrefs = set() @@ -294,9 +296,8 @@ def parse_source_xml(filename): annotations = get_text(get_child(member, 'argsstring')) if annotations and ')' in annotations: annotations = annotations.rsplit(')', 1)[-1].strip() - # XXX: (doxygen 1.8.11) 'argsstring' only includes FUNC_ATTR_* - # attributes if the function signature is non-void. - # Force attributes here for such functions. + # XXX: (doxygen 1.8.11) 'argsstring' only includes attributes of + # non-void functions. Special-case void functions here. if name == 'nvim_get_mode' and len(annotations) == 0: annotations += 'FUNC_API_ASYNC' annotations = filter(None, map(lambda x: annotation_map.get(x), @@ -379,7 +380,7 @@ def parse_source_xml(filename): if 'Deprecated' in xrefs: deprecated_functions.append(func_doc) - else: + elif name.startswith(api_func_name_prefix): functions.append(func_doc) xrefs.clear() -- cgit From fe60fa9faafd90cfe756c80119abae6f8906fc4b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 16 Dec 2017 21:33:59 +0100 Subject: doc vim-patch:8.0.1206: no autocmd for entering or leaving the command line (commit a4f6cec7a31ff8dbfa089b9e22227afbeb951e9b) NA patches: vim-patch:8.0.0320: warning for unused variable with small build --- scripts/gen_api_vimdoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/gen_api_vimdoc.py') diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py index 4ddf415f1a..69f70f6e2b 100644 --- a/scripts/gen_api_vimdoc.py +++ b/scripts/gen_api_vimdoc.py @@ -478,7 +478,7 @@ def gen_docs(config): docs += '\n\n\n' docs = docs.rstrip() + '\n\n' - docs += ' vim:tw=78:ts=8:ft=help:norl:' + docs += ' vim:tw=78:ts=8:ft=help:norl:\n' doc_file = os.path.join(base_dir, 'runtime/doc', doc_filename) delete_lines_below(doc_file, section_start_token) -- cgit