From 3fd504dbec39eeced1bea17d9f3bd06de7f3e4d8 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Sun, 16 Jul 2023 09:34:50 +0100 Subject: [PATCH] docs: handle whitespace in emmycomments --- runtime/doc/lsp.txt | 12 ++-- runtime/doc/lua.txt | 127 +++++++++++++++++++------------------ runtime/doc/treesitter.txt | 49 +++++++------- scripts/lua2dox.lua | 2 + 4 files changed, 100 insertions(+), 90 deletions(-) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 450690fe3b..5de3e98b5a 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -1189,8 +1189,8 @@ format({options}) *vim.lsp.buf.format()* server clients. Parameters: ~ - • {options} table|nil Optional table which holds the following optional - fields: + • {options} (table|nil) Optional table which holds the following + optional fields: • formatting_options (table|nil): Can be used to specify FormattingOptions. Some unspecified options will be automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions @@ -1204,10 +1204,10 @@ format({options}) *vim.lsp.buf.format()* Receives a client as argument and must return a boolean. Clients matching the predicate are included. Example: • >lua - -- Never request typescript-language-server for formatting - vim.lsp.buf.format { - filter = function(client) return client.name ~= "tsserver" end - } + -- Never request typescript-language-server for formatting + vim.lsp.buf.format { + filter = function(client) return client.name ~= "tsserver" end + } < • async boolean|nil If true the method won't block. Defaults to false. Editing the buffer while formatting diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index d7b023a4ec..81449bc454 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1423,15 +1423,16 @@ keycode({str}) *vim.keycode()* Translate keycodes. Example: >lua - local k = vim.keycode - vim.g.mapleader = k'' + + local k = vim.keycode + vim.g.mapleader = k'' < Parameters: ~ - • {str} string String to be converted. + • {str} (string) String to be converted. Return: ~ - string + (string) See also: ~ • |nvim_replace_termcodes()| @@ -1527,7 +1528,8 @@ print({...}) *vim.print()* "Pretty prints" the given arguments and returns them unmodified. Example: >lua - local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true)) + + local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true)) < Return: ~ @@ -1579,19 +1581,19 @@ system({cmd}, {opts}, {on_exit}) *vim.system()* Examples: >lua - local on_exit = function(obj) - print(obj.code) - print(obj.signal) - print(obj.stdout) - print(obj.stderr) - end + local on_exit = function(obj) + print(obj.code) + print(obj.signal) + print(obj.stdout) + print(obj.stderr) + end - -- Run asynchronously - vim.system({'echo', 'hello'}, { text = true }, on_exit) + -- Run asynchronously + vim.system({'echo', 'hello'}, { text = true }, on_exit) - -- Run synchronously - local obj = vim.system({'echo', 'hello'}, { text = true }):wait() - -- { code = 0, signal = 0, stdout = 'hello', stderr = '' } + -- Run synchronously + local obj = vim.system({'echo', 'hello'}, { text = true }):wait() + -- { code = 0, signal = 0, stdout = 'hello', stderr = '' } < See |uv.spawn()| for more details. @@ -1775,8 +1777,8 @@ gsplit({s}, {sep}, {opts}) *vim.gsplit()* < Parameters: ~ - • {s} string String to split - • {sep} string Separator or pattern + • {s} (string) String to split + • {sep} (string) Separator or pattern • {opts} (table|nil) Keyword arguments |kwargs|: • plain: (boolean) Use `sep` literally (as in string.find). • trimempty: (boolean) Discard empty segments at start and end @@ -2501,7 +2503,8 @@ get_option({filetype}, {option}) *vim.filetype.get_option()* files. Example: >lua - vim.filetype.get_option('vim', 'commentstring') + + vim.filetype.get_option('vim', 'commentstring') < Note: this uses |nvim_get_option_value()| but caches the result. This @@ -2509,8 +2512,8 @@ get_option({filetype}, {option}) *vim.filetype.get_option()* may not reflect later changes. Parameters: ~ - • {filetype} string Filetype - • {option} string Option name + • {filetype} (string) Filetype + • {option} (string) Option name Return: ~ string|boolean|integer: Option value @@ -2649,7 +2652,7 @@ dir({path}, {opts}) *vim.fs.dir()* • {path} (string) An absolute or relative path to the directory to iterate over. The path is first normalized |vim.fs.normalize()|. - • {opts} table|nil Optional keyword arguments: + • {opts} (table|nil) Optional keyword arguments: • depth: integer|nil How deep the traverse (default 1) • skip: (fun(dir_name: string): boolean)|nil Predicate to control traversal. Return false to stop searching the @@ -2847,10 +2850,10 @@ and dependencies on the current system. Example: >lua - local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) - if vim.version.gt(v, {3, 2, 0}) then - -- ... - end + local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) + if vim.version.gt(v, {3, 2, 0}) then + -- ... + end < @@ -2864,33 +2867,33 @@ tested against a version, using |vim.version.range()|. Supported range specs are shown in the following table. Note: suffixed versions (1.2.3-rc1) are not matched. > - 1.2.3 is 1.2.3 - =1.2.3 is 1.2.3 - >1.2.3 greater than 1.2.3 - <1.2.3 before 1.2.3 - >=1.2.3 at least 1.2.3 - ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" - ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" - ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) - ^0.0.1 is =0.0.1 (0.0.x is special) - ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) - ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) - ^1 is >=1.0.0 <2.0.0 "compatible with 1" - ~1 same "reasonably close to 1" - 1.x same - 1.* same - 1 same - * any version - x same + 1.2.3 is 1.2.3 + =1.2.3 is 1.2.3 + >1.2.3 greater than 1.2.3 + <1.2.3 before 1.2.3 + >=1.2.3 at least 1.2.3 + ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" + ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" + ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) + ^0.0.1 is =0.0.1 (0.0.x is special) + ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) + ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) + ^1 is >=1.0.0 <2.0.0 "compatible with 1" + ~1 same "reasonably close to 1" + 1.x same + 1.* same + 1 same + * any version + x same - 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 + 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 - Partial right: missing pieces treated as x (2.3 => 2.3.x). - 1.2.3 - 2.3 is >=1.2.3 <2.4.0 - 1.2.3 - 2 is >=1.2.3 <3.0.0 + Partial right: missing pieces treated as x (2.3 => 2.3.x). + 1.2.3 - 2.3 is >=1.2.3 <2.4.0 + 1.2.3 - 2 is >=1.2.3 <3.0.0 - Partial left: missing pieces treated as 0 (1.2 => 1.2.0). - 1.2 - 2.3.0 is 1.2.0 - 2.3.0 + Partial left: missing pieces treated as 0 (1.2 => 1.2.0). + 1.2 - 2.3.0 is 1.2.0 - 2.3.0 < @@ -2985,11 +2988,11 @@ parse({version}, {opts}) *vim.version.parse()* range({spec}) *vim.version.range()* Parses a semver |version-range| "spec" and returns a range object: > - { - from: Version - to: Version - has(v: string|Version) - } + { + from: Version + to: Version + has(v: string|Version) + } < `:has()` checks if a version is in the range (inclusive `from`, exclusive @@ -2997,20 +3000,20 @@ range({spec}) *vim.version.range()* Example: >lua - local r = vim.version.range('1.0.0 - 2.0.0') - print(r:has('1.9.9')) -- true - print(r:has('2.0.0')) -- false - print(r:has(vim.version())) -- check against current Nvim version + local r = vim.version.range('1.0.0 - 2.0.0') + print(r:has('1.9.9')) -- true + print(r:has('2.0.0')) -- false + print(r:has(vim.version())) -- check against current Nvim version < Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: >lua - local r = vim.version.range('1.0.0 - 2.0.0') - print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) + local r = vim.version.range('1.0.0 - 2.0.0') + print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) < Parameters: ~ - • {spec} string Version range "spec" + • {spec} (string) Version range "spec" See also: ~ • # https://github.com/npm/node-semver#ranges diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 9f17b9fb54..bb0d435f4a 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -793,17 +793,17 @@ get_filetypes({lang}) *vim.treesitter.language.get_filetypes()* Get the filetypes associated with the parser named {lang}. Parameters: ~ - • {lang} string Name of parser + • {lang} (string) Name of parser Return: ~ string[] filetypes get_lang({filetype}) *vim.treesitter.language.get_lang()* Parameters: ~ - • {filetype} string + • {filetype} (string) Return: ~ - string|nil + (string|nil) inspect({lang}) *vim.treesitter.language.inspect()* Inspects the provided language. @@ -821,7 +821,7 @@ register({lang}, {filetype}) *vim.treesitter.language.register()* Register a parser named {lang} to be used for {filetype}(s). Parameters: ~ - • {lang} string Name of parser + • {lang} (string) Name of parser • {filetype} string|string[] Filetype(s) to associate with lang @@ -1051,7 +1051,9 @@ contents. To create a LanguageTree (parser object) for a given buffer and language, use: >lua - local parser = vim.treesitter.get_parser(bufnr, lang) + + local parser = vim.treesitter.get_parser(bufnr, lang) + < (where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. @@ -1062,7 +1064,9 @@ it wants incremental updates. Whenever you need to access the current syntax tree, parse the buffer: >lua - local tree = parser:parse() + + local tree = parser:parse() + < This returns a table of immutable |treesitter-tree| objects representing @@ -1175,22 +1179,23 @@ LanguageTree:register_cbs({cbs}, {recursive}) Registers callbacks for the |LanguageTree|. Parameters: ~ - • {cbs} (table) An |nvim_buf_attach()|-like table argument with - the following handlers: - • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. - • `on_changedtree` : a callback that will be called - every time the tree has syntactical changes. It will - be passed two arguments: a table of the ranges (as - node ranges) that changed and the changed tree. - • `on_child_added` : emitted when a child is added to - the tree. - • `on_child_removed` : emitted when a child is removed - from the tree. - • `on_detach` : emitted when the buffer is detached, see - |nvim_buf_detach_event|. Takes one argument, the - number of the buffer. - • {recursive?} boolean Apply callbacks recursively for all children. - Any new children will also inherit the callbacks. + • {cbs} (table) An |nvim_buf_attach()|-like table argument with + the following handlers: + • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. + • `on_changedtree` : a callback that will be called every + time the tree has syntactical changes. It will be + passed two arguments: a table of the ranges (as node + ranges) that changed and the changed tree. + • `on_child_added` : emitted when a child is added to the + tree. + • `on_child_removed` : emitted when a child is removed + from the tree. + • `on_detach` : emitted when the buffer is detached, see + |nvim_buf_detach_event|. Takes one argument, the number + of the buffer. + • {recursive} (boolean|nil) Apply callbacks recursively for all + children. Any new children will also inherit the + callbacks. LanguageTree:source() *LanguageTree:source()* Returns the source content of the language tree (bufnr or string). 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 .. '"')