https://developer.apple.com/design/human-interface-guidelines/writing
    - "...without being overly colloquial or frivolous."
      https://developers.google.com/style/tone
- Write docstrings (as opposed to inline comments) with present tense ("Gets"),
  not imperative ("Get"). This tends to reduce ambiguity and improve clarity
  by describing "What" instead of "How". >
    ✅ OK:
    /// Gets a highlight definition.
    ❌ NO:
    /// Get a highlight definition.
- Avoid starting docstrings with "The" or "A" unless needed to avoid
  ambiguity. This is a visual aid and reduces noise. >
    ✅ OK:
    /// @param dirname Path fragment before `pend`
    ❌ NO:
    /// @param dirname The path fragment before `pend`
- Vim differences:
    - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
      differences from Vim; no other distinction is necessary.
    - If a Vim feature is removed, delete its help section and move its tag to
      |vim_diff.txt|.
- Mention deprecated features in |deprecated.txt| and delete their old doc.
- Use consistent language.
    - "terminal" in a help tag always means "the embedded terminal emulator",
      not "the user host terminal".
    - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
      in prose if possible.
- Rough guidelines on where Lua documentation should end up:
    - Nvim API functions `vim.api.nvim_*` should be in `api.txt`.
    - If the module is big and not relevant to generic and lower-level Lua
      functionality, then it's a strong candidate for separation. Example:
      `treesitter.txt`
    - Otherwise, add them to `lua.txt`

Documentation format ~

For Nvim-owned docs, use the following strict subset of "vimdoc" to ensure
the help doc renders nicely in other formats (such as HTML:
https://neovim.io/doc/user ).

Strict "vimdoc" subset:

- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you
  don't want to auto-wrap. Lists are always rendered with "flow" layout
  (soft-wrapped) instead of preformatted (hard-wrapped) layout common in
  legacy :help docs.
  - Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc
    does not understand numbered listitems, so use a bullet symbol (- or •)
    before numbered items, e.g. "• 1." instead of "1.".
- Separate blocks (paragraphs) of content by a blank line.
- 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 (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`, `@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`

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,