mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
docs: remove "#" comment char in @return
Everything after a "#" char is a "description" comment, i.e. luals won't treat it as a type, name, etc. But "#" should not be present in the generated docs (such as :help docs). https://github.com/LuaLS/lua-language-server/wiki/Annotations#return
This commit is contained in:
parent
d2f8133024
commit
b1fb04475e
@ -289,7 +289,8 @@ For convenience you can filter the regeneration by target (api, lua, lsp) using
|
||||
|
||||
### Lua docstrings
|
||||
|
||||
Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua][dev-doc-lua].
|
||||
Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return
|
||||
types, etc. See [:help dev-doc-lua][dev-doc-lua].
|
||||
|
||||
- The template for function documentation is:
|
||||
```lua
|
||||
@ -340,7 +341,7 @@ as context, use the `-W` argument as well.
|
||||
[conventional_commits]: https://www.conventionalcommits.org
|
||||
[dev-doc-guide]: https://neovim.io/doc/user/develop.html#dev-doc
|
||||
[dev-doc-lua]: https://neovim.io/doc/user/develop.html#dev-lua-doc
|
||||
[EmmyLua]: https://github.com/sumneko/lua-language-server/wiki/Annotations
|
||||
[LuaLS]: https://github.com/LuaLS/lua-language-server/wiki/Annotations
|
||||
[gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
|
||||
[gh]: https://cli.github.com/
|
||||
[git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
|
||||
|
@ -226,6 +226,7 @@ Lua documentation lives in the source code, as docstrings on the function
|
||||
definitions. The |lua-vim| :help is generated from the docstrings.
|
||||
|
||||
Docstring format:
|
||||
- Use LuaLS annotations: https://github.com/LuaLS/lua-language-server/wiki/Annotations
|
||||
- Lines in the main description start with `---`
|
||||
- Special tokens start with `---@` followed by the token name:
|
||||
`---@see`, `---@param`, `---@returns`
|
||||
|
@ -1569,7 +1569,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
|
||||
• {backtrace} boolean|nil Prints backtrace. Defaults to true.
|
||||
|
||||
Return: ~
|
||||
(string|nil) # Deprecated message, or nil if no message was shown.
|
||||
(string|nil) Deprecated message, or nil if no message was shown.
|
||||
|
||||
vim.inspect *vim.inspect()*
|
||||
Gets a human-readable representation of the given object.
|
||||
@ -1693,7 +1693,7 @@ vim.print({...}) *vim.print()*
|
||||
<
|
||||
|
||||
Return: ~
|
||||
any # given arguments.
|
||||
any given arguments.
|
||||
|
||||
See also: ~
|
||||
• |vim.inspect()|
|
||||
@ -2080,7 +2080,7 @@ vim.spairs({t}) *vim.spairs()*
|
||||
• {t} (table) Dict-like table
|
||||
|
||||
Return: ~
|
||||
_ iterator over sorted keys and their values
|
||||
iterator over sorted keys and their values
|
||||
|
||||
See also: ~
|
||||
• Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
|
||||
@ -2545,8 +2545,8 @@ vim.ui.open({path}) *vim.ui.open()*
|
||||
• {path} (string) Path or URL to open
|
||||
|
||||
Return (multiple): ~
|
||||
SystemCompleted|nil # Command result, or nil if not found.
|
||||
(string|nil) # Error message on failure
|
||||
SystemCompleted|nil Command result, or nil if not found.
|
||||
(string|nil) Error message on failure
|
||||
|
||||
See also: ~
|
||||
• |vim.system()|
|
||||
|
@ -154,6 +154,8 @@ local function removeCommentFromLine(line)
|
||||
return line:sub(1, pos_comment - 1), line:sub(pos_comment)
|
||||
end
|
||||
|
||||
--- Processes "@…" directives in a docstring line.
|
||||
---
|
||||
--- @param line string
|
||||
--- @param generics table<string,string>
|
||||
--- @return string?
|
||||
@ -206,6 +208,8 @@ local function process_magic(line, generics)
|
||||
magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1')
|
||||
magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1')
|
||||
end
|
||||
-- Remove first "#" comment char, if any. https://github.com/LuaLS/lua-language-server/wiki/Annotations#return
|
||||
magic = magic:gsub('# ', '', 1)
|
||||
-- handle the return of vim.spell.check
|
||||
magic = magic:gsub('({.*}%[%])', '`%1`')
|
||||
magic_split = vim.split(magic, ' ', { plain = true })
|
||||
|
Loading…
Reference in New Issue
Block a user