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`

Example: the help for |nvim_open_win()| is generated from a docstring defined
in src/nvim/api/win_config.c like this: >

    /// Opens a new window.
    /// ...
    ///
    /// Example (Lua): window-relative float
    ///
    /// ```lua
    /// vim.api.nvim_open_win(0, false, {
    ///   relative='win',
    ///   row=3,
    ///   col=3,
    ///   width=12,
    ///   height=3,
    /// })
    /// ```
    ///
    /// @param buffer Buffer to display
    /// @param enter  Enter the window
    /// @param config Map defining the window configuration. Keys:
    ///   - relative: Sets the window layout, relative to:
    ///      - "editor" The global editor grid.
    ///      - "win"    Window given by the `win` field.
    ///      - "cursor" Cursor position in current window.
    /// ...
    /// @param[out] err Error details, if any
    ///
    /// @return Window handle, or 0 on error


Lua docstrings ~
                                                        *dev-lua-doc*
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 LuaCATS annotations: https://luals.github.io/wiki/annotations/
- 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 `@since <api-level>` to note the |api-level| when the function became
  "stable". If `<api-level>` is greater than the current stable release (or
  0), it is marked as "experimental".
  - See scripts/util.lua for the mapping of api-level to Nvim version.
- 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 declared as `@meta` are only used for typing and documentation (similar to "*.d.ts" typescript files).

Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in runtime/lua/vim/_editor.lua like this: >

    --- Paste handler, invoked by |nvim_paste()| when a conforming UI
    --- (such as the |TUI|) pastes text into the editor.
    ---
    --- Example: To remove ANSI color codes when pasting:
    ---
    --- ```lua
    --- vim.paste = (function()
    ---   local overridden = vim.paste
    ---   ...
    --- end)()
    --- ```
    ---
    --- @since 12
    --- @see |paste|
    ---
    --- @param lines  ...
    --- @param phase  ...
    --- @returns false if client should cancel the paste.


STDLIB DESIGN GUIDELINES                                             *dev-lua*

See also |dev-naming|.

- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
  pseudo-OOP designs. Plugin authors just want functions to call, not a big,
  fancy inheritance hierarchy.
- Avoid requiring or returning special objects in the Nvim stdlib. Plain
  tables or values are easier to serialize, easier to construct from literals,
  easier to inspect and print, and inherently compatible with all Lua plugins.
  (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
- stdlib functions should follow these common patterns:
  - Return |lua-result-or-message| (`any|nil,nil|string`) to communicate
    failure, or choose from |dev-error-patterns| when appropriate.
  - Accept iterable instead of only table.
    - Note: in some cases