From 9ef16a1628722958b6e14fe9274006e50ed6682d Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sun, 27 Oct 2019 15:05:59 -0700
Subject: doc: vim.fn, vim.call(), vim.api [ci skip]

---
 runtime/doc/develop.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

(limited to 'runtime/doc/develop.txt')

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 90c2e30771..ba887a83c8 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -143,6 +143,87 @@ DOCUMENTATION						*dev-doc*
       /// @param dirname The path fragment before `pend`
 <
 
+C docstrings ~
+
+Nvim API documentation lives in the source code, as docstrings (Doxygen
+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")
+- Use `<pre>`  for code samples.
+
+Example: the help for |nvim_open_win()| is generated from a docstring defined
+in src/nvim/api/vim.c like this: >
+
+    /// Opens a new window.
+    /// ...
+    ///
+    /// Example (Lua): window-relative float
+    /// <pre>
+    ///     vim.api.nvim_open_win(0, false,
+    ///       {relative='win', row=3, col=3, width=12, height=3})
+    /// </pre>
+    ///
+    /// @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:
+- Lines in the main description start with `---`
+- Special tokens start with `--@` followed by the token name:
+  `--@see`, `--@param`, `--@returns`
+- Limited markdown is supported.
+  - List-items start with `-` (useful to nest or "indent")
+- Use `<pre>`  for code samples.
+
+Example: the help for |vim.paste()| is generated from a docstring decorating
+vim.paste in src/nvim/lua/vim.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:
+    --- <pre>
+    --- vim.paste = (function()
+    ---   local overridden = vim.paste
+    ---   ...
+    --- end)()
+    --- </pre>
+    ---
+    --@see |paste|
+    ---
+    --@param lines  ...
+    --@param phase  ...
+    --@returns false if client should cancel the paste.
+
+
+LUA							*dev-lua*
+
+- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
+  pseudo-OOP designs. Plugin authors just want functions to call, they don't
+  want to learn a big, fancy inheritance hierarchy. So we should avoid complex
+  objects: tables are usually better.
+
+
 API							*dev-api*
 
 Use this template to name new API functions:
-- 
cgit