From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- test/functional/script/luacats_grammar_spec.lua | 133 ++++++++++++++++++++++++ test/functional/script/text_utils_spec.lua | 39 +++++++ 2 files changed, 172 insertions(+) create mode 100644 test/functional/script/luacats_grammar_spec.lua create mode 100644 test/functional/script/text_utils_spec.lua (limited to 'test/functional/script') diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua new file mode 100644 index 0000000000..931fe42dd0 --- /dev/null +++ b/test/functional/script/luacats_grammar_spec.lua @@ -0,0 +1,133 @@ +local helpers = require('test.functional.helpers')(after_each) +local eq = helpers.eq + +local grammar = require('scripts/luacats_grammar') + +describe('luacats grammar', function() + --- @param text string + --- @param exp table + local function test(text, exp) + it(string.format('can parse %q', text), function() + eq(exp, grammar:match(text)) + end) + end + + test('@param hello vim.type', { + kind = 'param', + name = 'hello', + type = 'vim.type', + }) + + test('@param hello vim.type this is a description', { + kind = 'param', + name = 'hello', + type = 'vim.type', + desc = 'this is a description', + }) + + test('@param hello vim.type|string this is a description', { + kind = 'param', + name = 'hello', + type = 'vim.type|string', + desc = 'this is a description', + }) + + test('@param hello vim.type?|string? this is a description', { + kind = 'param', + name = 'hello', + type = 'vim.type?|string?', + desc = 'this is a description', + }) + + test('@return string hello this is a description', { + kind = 'return', + { + name = 'hello', + type = 'string', + }, + desc = 'this is a description', + }) + + test('@return fun() hello this is a description', { + kind = 'return', + { + name = 'hello', + type = 'fun()', + }, + desc = 'this is a description', + }) + + test('@return fun(a: string[]): string hello this is a description', { + kind = 'return', + { + name = 'hello', + type = 'fun(a: string[]): string', + }, + desc = 'this is a description', + }) + + test('@return fun(a: table): string hello this is a description', { + kind = 'return', + { + name = 'hello', + type = 'fun(a: table): string', + }, + desc = 'this is a description', + }) + + test('@param ... string desc', { + kind = 'param', + name = '...', + type = 'string', + desc = 'desc', + }) + + test('@param level (integer|string) desc', { + kind = 'param', + name = 'level', + type = 'integer|string', + desc = 'desc', + }) + + test('@return (string command) the command and arguments', { + kind = 'return', + { + name = 'command', + type = 'string', + }, + desc = 'the command and arguments', + }) + + test('@return (string command, string[] args) the command and arguments', { + kind = 'return', + { + name = 'command', + type = 'string', + }, + { + name = 'args', + type = 'string[]', + }, + desc = 'the command and arguments', + }) + + test('@param rfc "rfc2396" | "rfc2732" | "rfc3986" | nil', { + kind = 'param', + name = 'rfc', + type = '"rfc2396" | "rfc2732" | "rfc3986" | nil', + }) + + test('@param offset_encoding "utf-8" | "utf-16" | "utf-32" | nil', { + kind = 'param', + name = 'offset_encoding', + type = '"utf-8" | "utf-16" | "utf-32" | nil', + }) + + -- handle a : after the param type + test('@param a b: desc', { + kind = 'param', + name = 'a', + type = 'b', + desc = 'desc', + }) +end) diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua new file mode 100644 index 0000000000..c429d306d5 --- /dev/null +++ b/test/functional/script/text_utils_spec.lua @@ -0,0 +1,39 @@ +local helpers = require('test.functional.helpers')(after_each) +local exec_lua = helpers.exec_lua +local eq = helpers.eq + +local function md_to_vimdoc(text) + return exec_lua( + [[ + local text_utils = require('scripts/text_utils') + return text_utils.md_to_vimdoc(table.concat(..., '\n'), 0, 0, 70) + ]], + text + ) +end + +local function test(act, exp) + eq(table.concat(exp, '\n'), md_to_vimdoc(act)) +end + +describe('md_to_vimdoc', function() + before_each(function() + helpers.clear() + end) + + it('can render para after fenced code', function() + test({ + '- Para1', + ' ```', + ' code', + ' ```', + ' Para2', + }, { + '• Para1 >', + ' code', + '<', + ' Para2', + '', + }) + end) +end) -- cgit From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 27 Feb 2024 15:20:32 +0000 Subject: docs: improve/add documentation of Lua types - Added `@inlinedoc` so single use Lua types can be inlined into the functions docs. E.g. ```lua --- @class myopts --- @inlinedoc --- --- Documentation for some field --- @field somefield integer --- @param opts myOpts function foo(opts) end ``` Will be rendered as ``` foo(opts) Parameters: - {opts} (table) Object with the fields: - somefield (integer) Documentation for some field ``` - Marked many classes with with `@nodoc` or `(private)`. We can eventually introduce these when we want to. --- test/functional/script/luacats_parser_spec.lua | 106 +++++++++++++++++++++++++ test/functional/script/text_utils_spec.lua | 59 +++++++++----- 2 files changed, 145 insertions(+), 20 deletions(-) create mode 100644 test/functional/script/luacats_parser_spec.lua (limited to 'test/functional/script') diff --git a/test/functional/script/luacats_parser_spec.lua b/test/functional/script/luacats_parser_spec.lua new file mode 100644 index 0000000000..e10aa81003 --- /dev/null +++ b/test/functional/script/luacats_parser_spec.lua @@ -0,0 +1,106 @@ +local helpers = require('test.functional.helpers')(after_each) +local eq = helpers.eq + +local parser = require('scripts/luacats_parser') + +--- @param name string +--- @param text string +--- @param exp table +local function test(name, text, exp) + exp = vim.deepcopy(exp, true) + it(name, function() + eq(exp, parser.parse_str(text, 'myfile.lua')) + end) +end + +describe('luacats parser', function() + local exp = { + myclass = { + kind = 'class', + module = 'myfile.lua', + name = 'myclass', + fields = { + { kind = 'field', name = 'myclass', type = 'integer' }, + }, + }, + } + + test( + 'basic class', + [[ + --- @class myclass + --- @field myclass integer + ]], + exp + ) + + exp.myclass.inlinedoc = true + + test( + 'class with @inlinedoc (1)', + [[ + --- @class myclass + --- @inlinedoc + --- @field myclass integer + ]], + exp + ) + + test( + 'class with @inlinedoc (2)', + [[ + --- @inlinedoc + --- @class myclass + --- @field myclass integer + ]], + exp + ) + + exp.myclass.inlinedoc = nil + exp.myclass.nodoc = true + + test( + 'class with @nodoc', + [[ + --- @nodoc + --- @class myclass + --- @field myclass integer + ]], + exp + ) + + exp.myclass.nodoc = nil + exp.myclass.access = 'private' + + test( + 'class with (private)', + [[ + --- @class (private) myclass + --- @field myclass integer + ]], + exp + ) + + exp.myclass.fields[1].desc = 'Field\ndocumentation' + + test( + 'class with field doc above', + [[ + --- @class (private) myclass + --- Field + --- documentation + --- @field myclass integer + ]], + exp + ) + + exp.myclass.fields[1].desc = 'Field documentation' + test( + 'class with field doc inline', + [[ + --- @class (private) myclass + --- @field myclass integer Field documentation + ]], + exp + ) +end) diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua index c429d306d5..e644df92ae 100644 --- a/test/functional/script/text_utils_spec.lua +++ b/test/functional/script/text_utils_spec.lua @@ -2,18 +2,28 @@ local helpers = require('test.functional.helpers')(after_each) local exec_lua = helpers.exec_lua local eq = helpers.eq -local function md_to_vimdoc(text) +local function md_to_vimdoc(text, start_indent, indent, text_width) return exec_lua( [[ + local text, start_indent, indent, text_width = ... + start_indent = start_indent or 0 + indent = indent or 0 + text_width = text_width or 70 local text_utils = require('scripts/text_utils') - return text_utils.md_to_vimdoc(table.concat(..., '\n'), 0, 0, 70) + return text_utils.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width) ]], - text + text, + start_indent, + indent, + text_width ) end -local function test(act, exp) - eq(table.concat(exp, '\n'), md_to_vimdoc(act)) +local function test(what, act, exp, ...) + local argc, args = select('#', ...), { ... } + it(what, function() + eq(table.concat(exp, '\n'), md_to_vimdoc(act, unpack(args, 1, argc))) + end) end describe('md_to_vimdoc', function() @@ -21,19 +31,28 @@ describe('md_to_vimdoc', function() helpers.clear() end) - it('can render para after fenced code', function() - test({ - '- Para1', - ' ```', - ' code', - ' ```', - ' Para2', - }, { - '• Para1 >', - ' code', - '<', - ' Para2', - '', - }) - end) + test('can render para after fenced code', { + '- Para1', + ' ```', + ' code', + ' ```', + ' Para2', + }, { + '• Para1 >', + ' code', + '<', + ' Para2', + '', + }) + + test('start_indent only applies to first line', { + 'para1', + '', + 'para2', + }, { + 'para1', + '', + ' para2', + '', + }, 0, 10, 78) end) -- cgit From a4290f462ed7dc81e17b09bd27877b106b24b6bd Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 5 Mar 2024 12:06:15 +0000 Subject: docs(lua): improvements for LSP and Diagnostic --- test/functional/script/luacats_grammar_spec.lua | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'test/functional/script') diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua index 931fe42dd0..0fc2e4b95a 100644 --- a/test/functional/script/luacats_grammar_spec.lua +++ b/test/functional/script/luacats_grammar_spec.lua @@ -130,4 +130,13 @@ describe('luacats grammar', function() type = 'b', desc = 'desc', }) + + test( + '@field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', + { + kind = 'field', + name = 'prefix?', + type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', + } + ) end) -- cgit From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 8 Mar 2024 12:25:18 +0000 Subject: docs: support inline markdown - Tags are now created with `[tag]()` - References are now created with `[tag]` - Code spans are no longer wrapped --- test/functional/script/luacats_grammar_spec.lua | 12 ++++++++++++ test/functional/script/text_utils_spec.lua | 2 ++ 2 files changed, 14 insertions(+) (limited to 'test/functional/script') diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua index 0fc2e4b95a..c3ac9fe722 100644 --- a/test/functional/script/luacats_grammar_spec.lua +++ b/test/functional/script/luacats_grammar_spec.lua @@ -139,4 +139,16 @@ describe('luacats grammar', function() type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', } ) + + test('@field [integer] integer', { + kind = 'field', + name = '[integer]', + type = 'integer', + }) + + test('@field [1] integer', { + kind = 'field', + name = '[1]', + type = 'integer', + }) end) diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua index e644df92ae..190c617e1d 100644 --- a/test/functional/script/text_utils_spec.lua +++ b/test/functional/script/text_utils_spec.lua @@ -55,4 +55,6 @@ describe('md_to_vimdoc', function() ' para2', '', }, 0, 10, 78) + + test('inline 1', { '(`string`)' }, { '(`string`)', '' }) end) -- cgit