doc: vim.fn, vim.call(), vim.api [ci skip]

6 files changed, 192 insertions, 76 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 98dd330b48..d6e420c427 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -850,10 +850,10 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                     {enter}   Enter the window (make it the current window)
                     {config}  Map defining the window configuration. Keys:
                               •  `relative` : Sets the window layout to "floating", placed
-                                at (row,col) coordinates relative to one of:
+                                at (row,col) coordinates relative to:
                                 • "editor" The global editor grid
                                 • "win" Window given by the `win` field, or
-                                  current window by default.
+                                  current window.
                                 • "cursor" Cursor position in current window.
 
                               • `win` : |window-ID| for relative="win".
@@ -1476,45 +1476,66 @@ nvim_buf_line_count({buffer})                          *nvim_buf_line_count()*
                     Line count, or 0 for unloaded buffer. |api-buffer|
 
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
-                Activates buffer-update events on a channel, or as lua
+                Activates buffer-update events on a channel, or as Lua
                 callbacks.
 
                 Parameters: ~
                     {buffer}       Buffer handle, or 0 for current buffer
-                    {send_buffer}  Set to true if the initial notification
-                                   should contain the whole buffer. If so, the
-                                   first notification will be a
-                                   `nvim_buf_lines_event` . Otherwise, the
-                                   first notification will be a
-                                   `nvim_buf_changedtick_event` . Not used for
-                                   lua callbacks.
+                    {send_buffer}  True if the initial notification should
+                                   contain the whole buffer: first
+                                   notification will be `nvim_buf_lines_event`
+                                   . Else the first notification will be
+                                   `nvim_buf_changedtick_event` . Not for Lua
+                                   callbacks.
                     {opts}         Optional parameters.
-                                   • `on_lines` : lua callback received on
-                                     change.
-                                   • `on_changedtick` : lua callback received
-                                     on changedtick increment without text
-                                     change.
-                                   • `utf_sizes` : include UTF-32 and UTF-16
-                                     size of the replaced region. See
-                                     |api-buffer-updates-lua| for more
-                                     information
+                                   • on_lines: Lua callback invoked on change.
+                                     Return `true` to detach. Args:
+                                     • buffer handle
+                                     • b:changedtick
+                                     • first line that changed (zero-indexed)
+                                     • last line that was changed
+                                     • last line in the updated range
+                                     • byte count of previous contents
+                                     • deleted_codepoints (if `utf_sizes` is
+                                       true)
+                                     • deleted_codeunits (if `utf_sizes` is
+                                       true)
+
+                                   • on_changedtick: Lua callback invoked on
+                                     changedtick increment without text
+                                     change. Args:
+                                     • buffer handle
+                                     • b:changedtick
+
+                                   • on_detach: Lua callback invoked on
+                                     detach. Args:
+                                     • buffer handle
+
+                                   • utf_sizes: include UTF-32 and UTF-16 size
+                                     of the replaced region, as args to
+                                     `on_lines` .
+
+                Return: ~
+                    False if attach failed (invalid parameter, or buffer isn't
+                    loaded); otherwise True. TODO: LUA_API_NO_EVAL
 
-                Return: ~
-                    False when updates couldn't be enabled because the buffer
-                    isn't loaded or `opts` contained an invalid key; otherwise
-                    True. TODO: LUA_API_NO_EVAL
+                See also: ~
+                    |nvim_buf_detach()|
+                    |api-buffer-updates-lua|
 
 nvim_buf_detach({buffer})                                  *nvim_buf_detach()*
                 Deactivates buffer-update events on the channel.
 
-                For Lua callbacks see |api-lua-detach|.
-
                 Parameters: ~
                     {buffer}  Buffer handle, or 0 for current buffer
 
                 Return: ~
-                    False when updates couldn't be disabled because the buffer
-                    isn't loaded; otherwise True.
+                    False if detach failed (because the buffer isn't loaded);
+                    otherwise True.
+
+                See also: ~
+                    |nvim_buf_attach()|
+                    |api-lua-detach| for detaching Lua callbacks
 
                                                         *nvim_buf_get_lines()*
 nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
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:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index d21e441888..1eb873a5b4 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1217,7 +1217,7 @@ lambda expression				*expr-lambda* *lambda*
 {args -> expr1}		lambda expression
 
 A lambda expression creates a new unnamed function which returns the result of
-evaluating |expr1|.  Lambda expressions differ from |user-functions| in
+evaluating |expr1|.  Lambda expressions differ from |user-function|s in
 the following ways:
 
 1. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
@@ -1986,9 +1986,12 @@ v:windowid	Application-specific window "handle" which may be set by any
 		|window-ID|.
 
 ==============================================================================
-4. Builtin Functions					*functions*
+4. Builtin Functions				*vim-function* *functions*
 
-See |function-list| for a list grouped by what the function is used for.
+The Vimscript subsystem (referred to as "eval" internally) provides the
+following builtin functions.  Scripts can also define |user-function|s.
+
+See |function-list| to browse functions by topic.
 
 (Use CTRL-] on the function name to jump to the full explanation.)
 
@@ -3543,7 +3546,7 @@ exists({expr})	The result is a Number, which is |TRUE| if {expr} is
 					string)
 			*funcname	built-in function (see |functions|)
 					or user defined function (see
-					|user-functions|). Also works for a
+					|user-function|). Also works for a
 					variable that is a Funcref.
 			varname		internal variable (see
 					|internal-variables|).  Also works
@@ -9243,7 +9246,7 @@ Don't forget that "^" will only match at the first character of the String and
 "\n".
 
 ==============================================================================
-5. Defining functions					*user-functions*
+5. Defining functions					*user-function*
 
 New functions can be defined.  These can be called just like builtin
 functions.  The function executes a sequence of Ex commands.  Normal mode
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index fd2630d550..97d851a20f 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -285,7 +285,7 @@ Example: >
 
 Lua tables are used as both dictionaries and lists, so it is impossible to
 determine whether empty table is meant to be empty list or empty dictionary.
-Additionally lua does not have integer numbers. To distinguish between these
+Additionally Lua does not have integer numbers. To distinguish between these
 cases there is the following agreement:
 
 0. Empty table is empty list.
@@ -300,7 +300,7 @@ cases there is the following agreement:
 4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point 
    value:
    - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to 
-     a floating-point 1.0. Note that by default integral lua numbers are 
+     a floating-point 1.0. Note that by default integral Lua numbers are 
      converted to |Number|s, non-integral are converted to |Float|s. This 
      variant allows integral |Float|s.
    - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty 
@@ -321,10 +321,10 @@ Examples: >
     :  endfunction
     :echo Rand(1,10)
 
-Note that currently second argument to `luaeval` undergoes VimL to lua 
-conversion, so changing containers in lua do not affect values in VimL. Return 
-value is also always converted. When converting, |msgpack-special-dict|s are 
-treated specially.
+Note: second argument to `luaeval` undergoes VimL to Lua conversion
+("marshalled"), so changes to Lua containers do not affect values in VimL.
+Return value is also always converted. When converting,
+|msgpack-special-dict|s are treated specially.
 
 ==============================================================================
 Lua standard modules					*lua-stdlib*
@@ -355,22 +355,12 @@ Result is something like this: >
 
 To find documentation on e.g. the "deepcopy" function: >
 
-    :help vim.deepcopy
+    :help vim.deepcopy()
 
 Note that underscore-prefixed functions (e.g. "_os_proc_children") are
 internal/private and must not be used by plugins.
 
 ------------------------------------------------------------------------------
-VIM.API							*lua-api* *vim.api*
-
-`vim.api` exposes the full Nvim |API| as a table of Lua functions.
-
-Example: to use the "nvim_get_current_line()" API function, call
-"vim.api.nvim_get_current_line()": >
-
-    print(tostring(vim.api.nvim_get_current_line()))
-
-------------------------------------------------------------------------------
 VIM.LOOP						*lua-loop* *vim.loop*
 
 `vim.loop` exposes all features of the Nvim event-loop.  This is a low-level
@@ -503,7 +493,7 @@ it should call `parse()` again. If the buffer wasn't edited, the same tree will
 be returned again without extra work. If the buffer was parsed before,
 incremental parsing will be done of the changed parts.
 
-NB: to use the parser directly inside a |nvim_buf_attach| lua callback, you must
+NB: to use the parser directly inside a |nvim_buf_attach| Lua callback, you must
 call `get_parser()` before you register your callback. But preferably parsing
 shouldn't be done directly in the change callback anyway as they will be very
 frequent. Rather a plugin that does any kind of analysis on a tree should use
@@ -578,7 +568,17 @@ tsnode:named_descendant_for_range(start_row, start_col, end_row, end_col)
 	range of (row, column) positions
 
 ------------------------------------------------------------------------------
-VIM							*lua-util*
+VIM							*lua-builtin*
+
+vim.api.{func}({...})					*vim.api*
+        Invokes Nvim |API| function {func} with arguments {...}.
+        Example: call the "nvim_get_current_line()" API function: >
+            print(tostring(vim.api.nvim_get_current_line()))
+
+vim.call({func}, {...})					*vim.call()*
+        Invokes |vim-function| or |user-function| {func} with arguments {...}.
+        See also |vim.fn|. Equivalent to: >
+            vim.fn[func]({...})
 
 vim.in_fast_event()					*vim.in_fast_event()*
         Returns true if the code is executing as part of a "fast" event
@@ -614,26 +614,23 @@ vim.schedule({callback})				*vim.schedule()*
         Schedules {callback} to be invoked soon by the main event-loop. Useful
         to avoid |textlock| or other temporary restrictions.
 
-vim.fn.{func}({...})
-        Call vimL function {func} with arguments. {func} can be both builtin
-        functions and user functions. To call autoload functions, use the
-        syntax `vim.fn['some#function']({...})`
-
-        Note: unlike vim.api.|nvim_call_function| this converts values directly
-        between vimL values and lua values. If the vimL function returns a
-        float, it will be representeted directly as a lua number. Both empty
-        lists and dictonaries will be represented by an empty table.
-
-        Note: vim.fn keys are generated on demand. So `pairs(vim.fn)`
-        does NOT work to enumerate all functions.
+vim.fn.{func}({...})					*vim.fn*
+        Invokes |vim-function| or |user-function| {func} with arguments {...}.
+        To call autoload functions, use the syntax: >
+            vim.fn['some#function']({...})
+<
+        Unlike vim.api.|nvim_call_function| this converts directly between Vim
+        objects and Lua objects. If the Vim function returns a float, it will
+        be represented directly as a Lua number. Empty lists and dictionaries
+        both are represented by an empty table.
 
-vim.call({func}, {...})
-        Call vim script function {func}. Equivalent to `vim.fn[func]({...})`
+        Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+        enumerates functions that were called at least once.
 
 vim.type_idx						*vim.type_idx*
 	Type index for use in |lua-special-tbl|.  Specifying one of the 
 	values from |vim.types| allows typing the empty table (it is 
-	unclear whether empty lua table represents empty list or empty array) 
+	unclear whether empty Lua table represents empty list or empty array) 
 	and forcing integral numbers to be |Float|.  See |lua-special-tbl| for 
 	more details.
 
@@ -657,7 +654,7 @@ vim.types						*vim.types*
 	`vim.types.array` and `vim.types.dictionary` fall under only two 
 	following assumptions:
 	1. Value may serve both as a key and as a value in a table.  Given the 
-	   properties of lua tables this basically means “value is not `nil`”.
+	   properties of Lua tables this basically means “value is not `nil`”.
 	2. For each value in `vim.types` table `vim.types[vim.types[value]]` 
 	   is the same as `value`.
 	No other restrictions are put on types, and it is not guaranteed that 
@@ -679,6 +676,20 @@ paste({lines}, {phase})                                          *vim.paste()*
                 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: >
+
+                 vim.paste = (function()
+                   local overridden = vim.paste
+                   return function(lines, phase)
+                     for i,line in ipairs(lines) do
+                       -- Scrub ANSI color codes from paste input.
+                       lines[i] = line:gsub('\27%[[0-9;mK]+', '')
+                     end
+                     overridden(lines, phase)
+                   end
+                 end)()
+<
+
                 Parameters: ~
                     {lines}  |readfile()|-style list of lines to paste.
                              |channel-lines|
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 7221888074..211b7be2cc 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1170,7 +1170,7 @@ tag		command		action ~
 |:caddfile|	:caddf[ile]	add error message to current quickfix list
 |:call|		:cal[l]		call a function
 |:catch|	:cat[ch]	part of a :try command
-|:cbelow|	:cbe[low]	got to error below current line
+|:cbelow|	:cbe[low]	go to error below current line
 |:cbottom|	:cbo[ttom]	scroll to the bottom of the quickfix window
 |:cbuffer|	:cb[uffer]	parse error messages and jump to first error
 |:cc|		:cc		go to specific error
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 9e24ee0320..e93c833c76 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -418,35 +418,35 @@ between Vi and Vim.
 5. Text object motions					*object-motions*
 
 							*(*
-(			[count] sentences backward.  |exclusive| motion.
+(			[count] |sentence|s backward.  |exclusive| motion.
 
 							*)*
-)			[count] sentences forward.  |exclusive| motion.
+)			[count] |sentence|s forward.  |exclusive| motion.
 
 							*{*
-{			[count] paragraphs backward.  |exclusive| motion.
+{			[count] |paragraph|s backward.  |exclusive| motion.
 
 							*}*
-}			[count] paragraphs forward.  |exclusive| motion.
+}			[count] |paragraph|s forward.  |exclusive| motion.
 
 							*]]*
-]]			[count] sections forward or to the next '{' in the
+]]			[count] |section|s forward or to the next '{' in the
 			first column.  When used after an operator, then also
 			stops below a '}' in the first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.
 
 							*][*
-][			[count] sections forward or to the next '}' in the
+][			[count] |section|s forward or to the next '}' in the
 			first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.
 
 							*[[*
-[[			[count] sections backward or to the previous '{' in
+[[			[count] |section|s backward or to the previous '{' in
 			the first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.
 
 							*[]*
-[]			[count] sections backward or to the previous '}' in
+[]			[count] |section|s backward or to the previous '}' in
 			the first column.  |exclusive|
 			Note that |exclusive-linewise| often applies.