From 5c9baa6f35262f75b73a82e4b2eba8f7cdf9db0a Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Thu, 25 Aug 2022 09:06:37 +0200 Subject: [PATCH] docs(contributing): add documenting guidelines from wiki (#19924) Co-authored-by: Thomas Vigouroux --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95f26d4722..582d5fbdd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 `. + +## 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