mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
docs(contributing): add documenting guidelines from wiki (#19924)
Co-authored-by: Thomas Vigouroux <thomas.vigouroux@protonmail.com>
This commit is contained in:
parent
170617c7a2
commit
5c9baa6f35
@ -266,6 +266,41 @@ For managing includes in C files, use [include-what-you-use].
|
||||
|
||||
See [#549][549] for more details.
|
||||
|
||||
Documenting
|
||||
-----------
|
||||
|
||||
Many parts of the `:help` documentation are autogenerated from C or Lua docstrings using the `./scripts/gen_vimdoc.py` script.
|
||||
You can filter the regeneration based on the target (api, lua, or lsp), or the file you changed, that need a doc refresh using `./scripts/gen_vimdoc.py -t <target>`.
|
||||
|
||||
## Lua docstrings
|
||||
|
||||
Lua documentation uses a subset of [EmmyLua] annotations. A rough outline of a function documentation is
|
||||
|
||||
```lua
|
||||
--- {Brief}
|
||||
---
|
||||
--- {Long explanation}
|
||||
---
|
||||
---@param arg1 type {description}
|
||||
---@param arg2 type {description}
|
||||
{...}
|
||||
---
|
||||
---@return type {description}
|
||||
```
|
||||
|
||||
If possible, always add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
|
||||
|
||||
If a function in your Lua module should not be documented (e.g. internal function or local function), you should set the doc comment to:
|
||||
|
||||
```
|
||||
---@private
|
||||
```
|
||||
|
||||
Mark functions that are deprecated as
|
||||
```
|
||||
---@deprecated
|
||||
```
|
||||
|
||||
Reviewing
|
||||
---------
|
||||
|
||||
@ -292,6 +327,7 @@ as context, use the `-W` argument as well.
|
||||
[Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
|
||||
[complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
|
||||
[conventional_commits]: https://www.conventionalcommits.org
|
||||
[EmmyLua]: https://github.com/sumneko/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
|
||||
|
Loading…
Reference in New Issue
Block a user