diff options
Diffstat (limited to 'runtime/doc/develop.txt')
| -rw-r--r-- | runtime/doc/develop.txt | 45 |
1 files changed, 36 insertions, 9 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index f1d74326c7..767f46ad1e 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -102,11 +102,11 @@ Examples: The provider framework invokes Vimscript from C. It is composed of two functions in eval.c: -- eval_call_provider(name, method, arguments, discard): calls - provider#{name}#Call with the method and arguments. If discard is true, any +- eval_call_provider({name}, {method}, {arguments}, {discard}): Calls + `provider#{name}#Call` with {method} and {arguments}. If {discard} is true, any value returned by the provider will be discarded and empty value will be returned. -- eval_has_provider(name): Checks the `g:loaded_{name}_provider` variable +- eval_has_provider({name}): Checks the `g:loaded_{name}_provider` variable which must be set to 2 by the provider script to indicate that it is "enabled and working". Called by |has()| to check if features are available. @@ -179,19 +179,22 @@ Strict "vimdoc" subset: - Do not use indentation in random places—that prevents the page from using "flow" layout. If you need a preformatted section, put it in a |help-codeblock| starting with ">". +- Parameters and fields are documented as `{foo}`. +- Optional parameters and fields are documented as `{foo}?`. C docstrings ~ -Nvim API documentation lives in the source code, as docstrings (Doxygen +Nvim API documentation lives in the source code, as docstrings (doc comments) on the function definitions. The |api| :help is generated from the docstrings defined in src/nvim/api/*.c. Docstring format: - Lines start with `///` - Special tokens start with `@` followed by the token name: - `@note`, `@param`, `@returns` -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") + `@note`, `@param`, `@return` +- Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` @@ -233,11 +236,35 @@ definitions. The |lua-vim| :help is generated from the docstrings. Docstring format: - Use LuaCATS annotations: https://luals.github.io/wiki/annotations/ -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") +- Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` - Use `@nodoc` to prevent documentation generation. +- Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. + E.g. >lua + --- Object with fields: + --- @class myOpts + --- @inlinedoc + --- + --- Documentation for some field + --- @field somefield? integer + + --- @param opts? myOpts + function foo(opts) + end +< + + Will be rendered as: >vimdoc + + foo({opts}) + + Parameters: + - {opts}? (table) Object with the fields: + - {somefield}? (integer) Documentation + for some field +< - Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating |