doc [ci skip] #9478

- Lua
- developer guidelines
- MAINTAIN.md
- TUI: cleanup
- TUI: mention Windows terminfo builtins
- cleanup if_pyth, redirect python-bindeval tag

Helped-by: Björn Linse <bjorn.linse@gmail.com>
Helped-by: erw7 <erw7.github@gmail.com>

4 files changed, 92 insertions, 85 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 5df0f0bb47..9cd178eaeb 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -104,7 +104,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
 ///        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`
-/// @param  opts  Optional parameters. Currently not used.
+/// @param  opts  Optional parameters. Reserved for future use.
 /// @param[out] err Details of an error that may have occurred
 /// @return False when updates couldn't be enabled because the buffer isn't
 ///         loaded or `opts` contained an invalid key; otherwise True.
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 7ba5251c60..bc8a1a941f 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -245,9 +245,8 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
                 name.data);
 }
 
-/// Tell nvim to resize a grid. Nvim sends grid_resize event with the
-/// requested grid size is within size limits and with maximum allowed size
-/// otherwise.
+/// Tell Nvim to resize a grid. Triggers a grid_resize event with the requested
+/// grid size or the maximum size if it exceeds size limits.
 ///
 /// On invalid grid handle, fails with error.
 ///
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 7f62333d88..5b59ff39f4 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -198,9 +198,8 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
 /// @note |keycodes| like <CR> are translated, so "<" is special.
 ///       To input a literal "<", send <LT>.
 ///
-/// For mouse events use |nvim_input_mouse()|. For back-compat reasons
-/// this method supports mouse input as "<LeftMouse><col,row>". This
-/// usage is deprecated since API level 6, use the dedicated method instead.
+/// @note For mouse events use |nvim_input_mouse()|. The pseudokey form
+///       "<LeftMouse><col,row>" is deprecated since |api-level| 6.
 ///
 /// @param keys to be typed
 /// @return Number of bytes actually written (can be fewer than
@@ -211,7 +210,7 @@ Integer nvim_input(String keys)
   return (Integer)input_enqueue(keys);
 }
 
-/// Send mouse event from GUI
+/// Send mouse event from GUI.
 ///
 /// The call is non-blocking. It doesn't wait on any resulting action, but
 /// queues the event to be processed soon by the event loop.
@@ -220,20 +219,18 @@ Integer nvim_input(String keys)
 ///       by calling it multiple times in a loop: the intermediate mouse
 ///       positions will be ignored. It should be used to implement real-time
 ///       mouse input in a GUI. The deprecated pseudokey form
-///       ("<LeftMouse><col,row>") in |nvim_input()| has the same limitiation.
+///       ("<LeftMouse><col,row>") of |nvim_input()| has the same limitiation.
 ///
-/// @param button Which mouse button, one of "left", "right", "middle" or
-///               "wheel".
-/// @param action For ordinary buttons, one of "press", "drag" and "release"
-///               For the wheel, use "up", "down", "left" and "right".
+/// @param button Mouse button: one of "left", "right", "middle", "wheel".
+/// @param action For ordinary buttons, one of "press", "drag", "release".
+///               For the wheel, one of "up", "down", "left", "right".
 /// @param modifier String of modifiers each represented by a single char.
 ///                 The same specifiers are used as for a key press, except
 ///                 that the "-" separator is optional, so "C-A-", "c-a"
-///                 and "CA" can all be used to specify Ctrl+Alt+click
-/// @param grid For a client using |ui-multigrid| pass in the grid number.
-///             Other clients should pass in 0 (not 1).
-/// @param row row position of mouse (zero-based, like in redraw events)
-/// @param col column position of mouse (zero-based, like in redraw events)
+///                 and "CA" can all be used to specify Ctrl+Alt+click.
+/// @param grid Grid number if the client uses |ui-multigrid|, else 0.
+/// @param row Mouse row-position (zero-based, like redraw events)
+/// @param col Mouse column-position (zero-based, like redraw events)
 void nvim_input_mouse(String button, String action, String modifier,
                       Integer grid, Integer row, Integer col, Error *err)
   FUNC_API_SINCE(6) FUNC_API_ASYNC
@@ -694,7 +691,7 @@ void nvim_set_current_dir(String dir, Error *err)
   try_end(err);
 }
 
-/// Gets the current line
+/// Gets the current line.
 ///
 /// @param[out] err Error details, if any
 /// @return Current line string
@@ -704,7 +701,7 @@ String nvim_get_current_line(Error *err)
   return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
 }
 
-/// Sets the current line
+/// Sets the current line.
 ///
 /// @param line     Line contents
 /// @param[out] err Error details, if any
@@ -714,7 +711,7 @@ void nvim_set_current_line(String line, Error *err)
   buffer_set_line(curbuf->handle, curwin->w_cursor.lnum - 1, line, err);
 }
 
-/// Deletes the current line
+/// Deletes the current line.
 ///
 /// @param[out] err Error details, if any
 void nvim_del_current_line(Error *err)
@@ -723,7 +720,7 @@ void nvim_del_current_line(Error *err)
   buffer_del_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
 }
 
-/// Gets a global (g:) variable
+/// Gets a global (g:) variable.
 ///
 /// @param name     Variable name
 /// @param[out] err Error details, if any
@@ -734,7 +731,7 @@ Object nvim_get_var(String name, Error *err)
   return dict_get_value(&globvardict, name, err);
 }
 
-/// Sets a global (g:) variable
+/// Sets a global (g:) variable.
 ///
 /// @param name     Variable name
 /// @param value    Variable value
@@ -745,7 +742,7 @@ void nvim_set_var(String name, Object value, Error *err)
   dict_set_var(&globvardict, name, value, false, false, err);
 }
 
-/// Removes a global (g:) variable
+/// Removes a global (g:) variable.
 ///
 /// @param name     Variable name
 /// @param[out] err Error details, if any
@@ -772,7 +769,7 @@ Object vim_del_var(String name, Error *err)
   return dict_set_var(&globvardict, name, NIL, true, true, err);
 }
 
-/// Gets a v: variable
+/// Gets a v: variable.
 ///
 /// @param name     Variable name
 /// @param[out] err Error details, if any
@@ -783,7 +780,7 @@ Object nvim_get_vvar(String name, Error *err)
   return dict_get_value(&vimvardict, name, err);
 }
 
-/// Sets a v: variable, if it is not readonly
+/// Sets a v: variable, if it is not readonly.
 ///
 /// @param name     Variable name
 /// @param value    Variable value
@@ -794,7 +791,7 @@ void nvim_set_vvar(String name, Object value, Error *err)
   dict_set_var(&vimvardict, name, value, false, false, err);
 }
 
-/// Gets an option value string
+/// Gets an option value string.
 ///
 /// @param name     Option name
 /// @param[out] err Error details, if any
@@ -805,7 +802,7 @@ Object nvim_get_option(String name, Error *err)
   return get_option_from(NULL, SREQ_GLOBAL, name, err);
 }
 
-/// Sets an option value
+/// Sets an option value.
 ///
 /// @param name     Option name
 /// @param value    New option value
@@ -873,7 +870,7 @@ ArrayOf(Buffer) nvim_list_bufs(void)
   return rv;
 }
 
-/// Gets the current buffer
+/// Gets the current buffer.
 ///
 /// @return Buffer handle
 Buffer nvim_get_current_buf(void)
@@ -882,7 +879,7 @@ Buffer nvim_get_current_buf(void)
   return curbuf->handle;
 }
 
-/// Sets the current buffer
+/// Sets the current buffer.
 ///
 /// @param buffer   Buffer handle
 /// @param[out] err Error details, if any
@@ -905,7 +902,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err)
   }
 }
 
-/// Gets the current list of window handles
+/// Gets the current list of window handles.
 ///
 /// @return List of window handles
 ArrayOf(Window) nvim_list_wins(void)
@@ -927,7 +924,7 @@ ArrayOf(Window) nvim_list_wins(void)
   return rv;
 }
 
-/// Gets the current window
+/// Gets the current window.
 ///
 /// @return Window handle
 Window nvim_get_current_win(void)
@@ -936,7 +933,7 @@ Window nvim_get_current_win(void)
   return curwin->handle;
 }
 
-/// Sets the current window
+/// Sets the current window.
 ///
 /// @param window Window handle
 void nvim_set_current_win(Window window, Error *err)
@@ -958,7 +955,7 @@ void nvim_set_current_win(Window window, Error *err)
   }
 }
 
-/// Gets the current list of tabpage handles
+/// Gets the current list of tabpage handles.
 ///
 /// @return List of tabpage handles
 ArrayOf(Tabpage) nvim_list_tabpages(void)
@@ -980,7 +977,7 @@ ArrayOf(Tabpage) nvim_list_tabpages(void)
   return rv;
 }
 
-/// Gets the current tabpage
+/// Gets the current tabpage.
 ///
 /// @return Tabpage handle
 Tabpage nvim_get_current_tabpage(void)
@@ -989,7 +986,7 @@ Tabpage nvim_get_current_tabpage(void)
   return curtab->handle;
 }
 
-/// Sets the current tabpage
+/// Sets the current tabpage.
 ///
 /// @param tabpage  Tabpage handle
 /// @param[out] err Error details, if any
@@ -1012,7 +1009,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
   }
 }
 
-/// Creates a new namespace, or gets an existing one
+/// Creates a new namespace, or gets an existing one.
 ///
 /// Namespaces are used for buffer highlights and virtual text, see
 /// |nvim_buf_add_highlight()| and |nvim_buf_set_virtual_text()|.
@@ -1038,7 +1035,7 @@ Integer nvim_create_namespace(String name)
   return (Integer)id;
 }
 
-/// Gets existing, non-anonymous namespaces
+/// Gets existing, non-anonymous namespaces.
 ///
 /// @return dict that maps from names to namespace ids.
 Dictionary nvim_get_namespaces(void)
@@ -1055,7 +1052,7 @@ Dictionary nvim_get_namespaces(void)
   return retval;
 }
 
-/// Subscribes to event broadcasts
+/// Subscribes to event broadcasts.
 ///
 /// @param channel_id Channel id (passed automatically by the dispatcher)
 /// @param event      Event type string
@@ -1069,7 +1066,7 @@ void nvim_subscribe(uint64_t channel_id, String event)
   rpc_subscribe(channel_id, e);
 }
 
-/// Unsubscribes to event broadcasts
+/// Unsubscribes to event broadcasts.
 ///
 /// @param channel_id Channel id (passed automatically by the dispatcher)
 /// @param event      Event type string
@@ -1379,7 +1376,7 @@ typedef struct {
 typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 /// @endcond
 
-/// Parse a VimL expression
+/// Parse a VimL expression.
 ///
 /// @param[in]  expr  Expression to parse. Is always treated as a single line.
 /// @param[in]  flags  Flags:
@@ -1860,7 +1857,7 @@ static void write_msg(String message, bool to_err)
 
 // Functions used for testing purposes
 
-/// Returns object given as argument
+/// Returns object given as argument.
 ///
 /// This API function is used for testing. One should not rely on its presence
 /// in plugins.
@@ -1873,7 +1870,7 @@ Object nvim__id(Object obj)
   return copy_object(obj);
 }
 
-/// Returns array given as argument
+/// Returns array given as argument.
 ///
 /// This API function is used for testing. One should not rely on its presence
 /// in plugins.
@@ -1886,7 +1883,7 @@ Array nvim__id_array(Array arr)
   return copy_object(ARRAY_OBJ(arr)).data.array;
 }
 
-/// Returns dictionary given as argument
+/// Returns dictionary given as argument.
 ///
 /// This API function is used for testing. One should not rely on its presence
 /// in plugins.
@@ -1899,7 +1896,7 @@ Dictionary nvim__id_dictionary(Dictionary dct)
   return copy_object(DICTIONARY_OBJ(dct)).data.dictionary;
 }
 
-/// Returns floating-point value given as argument
+/// Returns floating-point value given as argument.
 ///
 /// This API function is used for testing. One should not rely on its presence
 /// in plugins.
@@ -2023,19 +2020,19 @@ Object nvim_get_proc(Integer pid, Error *err)
   return rvobj;
 }
 
-/// Selects an item in the completion popupmenu
+/// Selects an item in the completion popupmenu.
 ///
-/// When insert completion is not active, this API call is silently ignored.
-/// It is mostly useful for an external UI using |ui-popupmenu| for instance
-/// to control the popupmenu with the mouse. But it can also be used in an
-/// insert mode mapping, use <cmd> mapping |:map-cmd| to ensure the mapping
-/// doesn't end completion mode.
+/// If |ins-completion| is not active this API call is silently ignored.
+/// Useful for an external UI using |ui-popupmenu| to control the popupmenu
+/// with the mouse. Can also be used in a mapping; use <cmd> |:map-cmd| to
+/// ensure the mapping doesn't end completion mode.
 ///
-/// @param item   Index of the item to select, starting with zero. Pass in "-1"
-///               to select no item (restore original text).
+/// @param item   Index (zero-based) of the item to select. Value of -1 selects
+///               nothing and restores the original text.
 /// @param insert Whether the selection should be inserted in the buffer.
-/// @param finish If true, completion will be finished with this item, and the
-///               popupmenu dissmissed. Implies `insert`.
+/// @param finish Finish the completion and dismiss the popupmenu. Implies
+///               `insert`.
+/// @param  opts  Optional parameters. Reserved for future use.
 void nvim_select_popupmenu_item(Integer item, Boolean insert, Boolean finish,
                                 Dictionary opts, Error *err)
   FUNC_API_SINCE(6)
diff --git a/src/nvim/memline_defs.h b/src/nvim/memline_defs.h
index 34a002af5d..edd933b2cd 100644
--- a/src/nvim/memline_defs.h
+++ b/src/nvim/memline_defs.h
@@ -3,54 +3,65 @@
 
 #include "nvim/memfile_defs.h"
 
-/*
- * When searching for a specific line, we remember what blocks in the tree
- * are the branches leading to that block. This is stored in ml_stack.  Each
- * entry is a pointer to info in a block (may be data block or pointer block)
- */
+///
+/// When searching for a specific line, we remember what blocks in the tree
+/// are the branches leading to that block. This is stored in ml_stack.  Each
+/// entry is a pointer to info in a block (may be data block or pointer block)
+///
 typedef struct info_pointer {
-  blocknr_T ip_bnum;            /* block number */
-  linenr_T ip_low;              /* lowest lnum in this block */
-  linenr_T ip_high;             /* highest lnum in this block */
-  int ip_index;                 /* index for block with current lnum */
-} infoptr_T;    /* block/index pair */
+  blocknr_T ip_bnum;            // block number
+  linenr_T ip_low;              // lowest lnum in this block
+  linenr_T ip_high;             // highest lnum in this block
+  int ip_index;                 // index for block with current lnum
+} infoptr_T;    // block/index pair
 
 typedef struct ml_chunksize {
   int mlcs_numlines;
   long mlcs_totalsize;
 } chunksize_T;
 
-/* Flags when calling ml_updatechunk() */
-
+// Flags when calling ml_updatechunk()
 #define ML_CHNK_ADDLINE 1
 #define ML_CHNK_DELLINE 2
 #define ML_CHNK_UPDLINE 3
 
-/*
- * the memline structure holds all the information about a memline
- */
+/// memline structure: the contents of a buffer.
+/// Essentially a tree with a branch factor of 128.
+/// Lines are stored at leaf nodes.
+/// Nodes are stored on ml_mfp (memfile_T):
+///   pointer_block: internal nodes
+///   data_block: leaf nodes
+///
+/// Memline also has "chunks" of 800 lines that are separate from the 128-tree
+/// structure, primarily used to speed up line2byte() and byte2line().
+///
+/// Motivation: If you have a file that is 10000 lines long, and you insert
+///             a line at linenr 1000, you don't want to move 9000 lines in
+///             memory.  With this structure it is roughly (N * 128) pointer
+///             moves, where N is the height (typically 1-3).
+///
 typedef struct memline {
-  linenr_T ml_line_count;       /* number of lines in the buffer */
+  linenr_T ml_line_count;       // number of lines in the buffer
 
-  memfile_T   *ml_mfp;          /* pointer to associated memfile */
+  memfile_T   *ml_mfp;          // pointer to associated memfile
 
-#define ML_EMPTY        1       /* empty buffer */
-#define ML_LINE_DIRTY   2       /* cached line was changed and allocated */
-#define ML_LOCKED_DIRTY 4       /* ml_locked was changed */
-#define ML_LOCKED_POS   8       /* ml_locked needs positive block number */
+#define ML_EMPTY        1       // empty buffer
+#define ML_LINE_DIRTY   2       // cached line was changed and allocated
+#define ML_LOCKED_DIRTY 4       // ml_locked was changed
+#define ML_LOCKED_POS   8       // ml_locked needs positive block number
   int ml_flags;
 
-  infoptr_T   *ml_stack;        /* stack of pointer blocks (array of IPTRs) */
-  int ml_stack_top;             /* current top of ml_stack */
-  int ml_stack_size;            /* total number of entries in ml_stack */
+  infoptr_T   *ml_stack;        // stack of pointer blocks (array of IPTRs)
+  int ml_stack_top;             // current top of ml_stack
+  int ml_stack_size;            // total number of entries in ml_stack
 
-  linenr_T ml_line_lnum;        /* line number of cached line, 0 if not valid */
-  char_u      *ml_line_ptr;     /* pointer to cached line */
+  linenr_T ml_line_lnum;        // line number of cached line, 0 if not valid
+  char_u      *ml_line_ptr;     // pointer to cached line
 
-  bhdr_T      *ml_locked;       /* block used by last ml_get */
-  linenr_T ml_locked_low;       /* first line in ml_locked */
-  linenr_T ml_locked_high;      /* last line in ml_locked */
-  int ml_locked_lineadd;            /* number of lines inserted in ml_locked */
+  bhdr_T      *ml_locked;       // block used by last ml_get
+  linenr_T ml_locked_low;       // first line in ml_locked
+  linenr_T ml_locked_high;      // last line in ml_locked
+  int ml_locked_lineadd;        // number of lines inserted in ml_locked
   chunksize_T *ml_chunksize;
   int ml_numchunks;
   int ml_usedchunks;