docs #22363

Co-authored by: zeertzjq <zeertzjq@outlook.com>
Co-authored by: Steven Todd McIntyre II <114119064+stmii@users.noreply.github.com>
Co-authored by: nobe4 <nobe4@users.noreply.github.com>

- docs: mention --luadev-mod to run with lua runtime files
  When changing a lua file in the ./runtime folder, a new contributor
  might expect changes to be applied to the built Neovim binary.

1 files changed, 40 insertions, 26 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c8387fbd2..91badd4c58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ Reporting problems
 Developer guidelines
 --------------------
 
-- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) if you are working on Nvim core.
+- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) and [:help dev-doc][dev-doc-guide] if you are working on Nvim core.
 - Read [:help dev-ui](https://neovim.io/doc/user/develop.html#dev-ui) if you are developing a UI.
 - Read [:help dev-api-client](https://neovim.io/doc/user/develop.html#dev-api-client) if you are developing an API client.
 - Install `ninja` for faster builds of Nvim.
@@ -264,40 +264,52 @@ For managing includes in C files, use [include-what-you-use].
 
 See [#549][549] for more details.
 
+### Lua runtime files
+
+Most of the Lua core [`runtime/`](./runtime) modules are precompiled to
+bytecode, so changes to those files won't get used unless you rebuild Nvim or
+by passing `--luamod-dev` and `$VIMRUNTIME`. For example, try adding a function
+to `runtime/lua/vim/_editor.lua` then:
+
+    VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev
+
 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>`.
+Read [:help dev-doc][dev-doc-guide] to understand the expected documentation style and conventions.
 
-## Lua docstrings
+### Generating :help
 
-Lua documentation uses a subset of [EmmyLua] annotations. A rough outline of a function documentation is
+Many `:help` docs are autogenerated from (C or Lua) docstrings by the `./scripts/gen_vimdoc.py` script.
+For convenience you can filter the regeneration by target (api, lua, lsp) using the `-t` option, for example:
 
-```lua
---- {Brief}
----
---- {Long explanation}
----
----@param arg1 type {description}
----@param arg2 type {description}
-{...}
----
----@return type {description}
-```
+    ./scripts/gen_vimdoc.py -t lua
 
-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`.
+### Lua docstrings
 
-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
-```
+Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua][dev-doc-lua].
 
-Mark functions that are deprecated as
-```
----@deprecated
-```
+- The template for function documentation is:
+  ```lua
+  --- {Brief}
+  ---
+  --- {Long explanation}
+  ---
+  ---@param arg1 type {description}
+  ---@param arg2 type {description}
+  --- ...
+  ---
+  ---@return type {description}
+  ```
+- If possible, 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 or local function), set the doc comment to:
+  ```
+  ---@private
+  ```
+- Mark deprecated functions with:
+  ```
+  ---@deprecated
+  ```
 
 Reviewing
 ---------
@@ -326,6 +338,8 @@ 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
+[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
 [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
 [gh]: https://cli.github.com/