doc: API (generated)

4 files changed, 91 insertions, 71 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 876adf0d72..ef8b9c7d47 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -135,6 +135,26 @@ nvim_command({command})                                       *nvim_command()*
                 Parameters:~
                     {command}  Ex-command string
 
+nvim_get_hl_by_name({name}, {rgb})                     *nvim_get_hl_by_name()*
+                Gets a highlight definition by name.
+
+                Parameters:~
+                    {name}  Highlight group name
+                    {rgb}   Export RGB colors
+
+                Return:~
+                    Highlight definition map
+
+nvim_get_hl_by_id({hl_id}, {rgb})                        *nvim_get_hl_by_id()*
+                Gets a highlight definition by id. |hlID()|
+
+                Parameters:~
+                    {hl_id}  Highlight id as returned by |hlID()|
+                    {rgb}    Export RGB colors
+
+                Return:~
+                    Highlight definition map
+
 nvim_feedkeys({keys}, {mode}, {escape_csi})                  *nvim_feedkeys()*
                 Passes input keys to Nvim. On VimL error: Does not fail, but
                 updates v:errmsg.
@@ -151,7 +171,11 @@ nvim_input({keys})                                              *nvim_input()*
 
                 Unlike `nvim_feedkeys`, this uses a lower-level input buffer
                 and the call is not deferred. This is the most reliable way to
-                emulate real user input.
+                send real user input.
+
+                Note:
+                    |keycodes| like <CR> are translated, so "<" is special. To
+                    input a literal "<", send <LT>.
 
                 Attributes:~
                     {async}
@@ -204,14 +228,11 @@ nvim_call_function({fname}, {args})                     *nvim_call_function()*
                     Result of the function call
 
 nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
-                Execute lua code. Parameters might be passed, they are
-                available inside the chunk as `...`. The chunk can return a
-                value.
+                Execute lua code. Parameters (if any) are available as `...`
+                inside the chunk. The chunk can return a value.
 
-                To evaluate an expression, it must be prefixed with "return ".
-                For instance, to call a lua function with arguments sent in
-                and get its return value back, use the code "return
-                my_function(...)".
+                Only statements are executed. To evaluate an expression,
+                prefix it with `return`: return my_function(...)
 
                 Parameters:~
                     {code}  lua code to execute
@@ -220,7 +241,7 @@ nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
                 Return:~
                     Return value of lua code if present or NIL.
 
-nvim_strwidth({str})                                         *nvim_strwidth()*
+nvim_strwidth({text})                                        *nvim_strwidth()*
                 Calculates the number of display cells occupied by `text`.
                 <Tab> counts as one cell.
 
@@ -347,7 +368,7 @@ nvim_set_current_buf({buffer})                        *nvim_set_current_buf()*
                 Sets the current buffer
 
                 Parameters:~
-                    {id}  Buffer handle
+                    {buffer}  Buffer handle
 
 nvim_list_wins()                                            *nvim_list_wins()*
                 Gets the current list of window handles
@@ -365,7 +386,7 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
                 Sets the current window
 
                 Parameters:~
-                    {handle}  Window handle
+                    {window}  Window handle
 
 nvim_list_tabpages()                                    *nvim_list_tabpages()*
                 Gets the current list of tabpage handles
@@ -383,7 +404,7 @@ nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
                 Sets the current tabpage
 
                 Parameters:~
-                    {handle}  Tabpage handle
+                    {tabpage}  Tabpage handle
 
 nvim_subscribe({event})                                     *nvim_subscribe()*
                 Subscribes to event broadcasts
@@ -404,26 +425,25 @@ nvim_get_color_map()                                    *nvim_get_color_map()*
                 TODO: Documentation
 
 nvim_get_mode()                                              *nvim_get_mode()*
-                Gets the current mode.
-                mode:     Mode string. |mode()|
-                blocking: true if Nvim is waiting for input.
-
-                Attributes:~
-                    {async}
+                Gets the current mode. |mode()| "blocking" is true if Nvim is
+                waiting for input.
 
                 Return:~
                     Dictionary { "mode": String, "blocking": Boolean }
 
+                Attributes:~
+                    {async}
+
 nvim_get_keymap({mode})                                    *nvim_get_keymap()*
-                Get a list of dictionaries describing global (i.e. non-buffer)
-                mappings Note that the "buffer" key will be 0 to represent
-                false.
+                Gets a list of dictionaries describing global (non-buffer)
+                mappings. The "buffer" key in the returned dictionary is
+                always zero.
 
                 Parameters:~
-                    {mode}  The abbreviation for the mode
+                    {mode}  Mode short-name ("n", "i", "v", ...)
 
                 Return:~
-                    An array of maparg() like dictionaries describing mappings
+                    Array of maparg()-like dictionaries describing mappings
 
 nvim_get_api_info()                                      *nvim_get_api_info()*
                 TODO: Documentation
@@ -584,16 +604,16 @@ nvim_buf_get_changedtick({buffer})                *nvim_buf_get_changedtick()*
                     b:changedtickvalue.
 
 nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
-                Get a list of dictionaries describing buffer-local mappings
-                Note that the buffer key in the dictionary will represent the
-                buffer handle where the mapping is present
+                Gets a list of dictionaries describing buffer-local mappings.
+                The "buffer" key in the returned dictionary reflects the
+                buffer handle where the mapping is present.
 
                 Parameters:~
-                    {mode}       The abbreviation for the mode
-                    {buffer_id}  Buffer handle
+                    {mode}    Mode short-name ("n", "i", "v", ...)
+                    {buffer}  Buffer handle
 
                 Return:~
-                    An array of maparg() like dictionaries describing mappings
+                    Array of maparg()-like dictionaries describing mappings
 
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
                 Sets a buffer-scoped (b:) variable
@@ -670,24 +690,24 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
                        {col_start}, {col_end})
                 Adds a highlight to buffer.
 
-                This can be used for plugins which dynamically generate
-                highlights to a buffer (like a semantic highlighter or
-                linter). The function adds a single highlight to a buffer.
-                Unlike matchaddpos() highlights follow changes to line
-                numbering (as lines are inserted/removed above the highlighted
-                line), like signs and marks do.
-
-                "src_id" is useful for batch deletion/updating of a set of
-                highlights. When called with src_id = 0, an unique source id
-                is generated and returned. Succesive calls can pass in it as
-                "src_id" to add new highlights to the same source group. All
-                highlights in the same group can then be cleared with
-                nvim_buf_clear_highlight. If the highlight never will be
-                manually deleted pass in -1 for "src_id".
-
-                If "hl_group" is the empty string no highlight is added, but a
-                new src_id is still returned. This is useful for an external
-                plugin to synchrounously request an unique src_id at
+                Useful for plugins that dynamically generate highlights to a
+                buffer (like a semantic highlighter or linter). The function
+                adds a single highlight to a buffer. Unlike matchaddpos()
+                highlights follow changes to line numbering (as lines are
+                inserted/removed above the highlighted line), like signs and
+                marks do.
+
+                `src_id` is useful for batch deletion/updating of a set of
+                highlights. When called with `src_id = 0`, an unique source id
+                is generated and returned. Successive calls can pass that
+                `src_id` to associate new highlights with the same source
+                group. All highlights in the same group can be cleared with
+                `nvim_buf_clear_highlight`. If the highlight never will be
+                manually deleted, pass `src_id = -1`.
+
+                If `hl_group` is the empty string no highlight is added, but a
+                new `src_id` is still returned. This is useful for an external
+                plugin to synchrounously request an unique `src_id` at
                 initialization, and later asynchronously add and clear
                 highlights in response to buffer changes.
 
@@ -696,7 +716,7 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
                     {src_id}     Source group to use or 0 to use a new group,
                                  or -1 for ungrouped highlight
                     {hl_group}   Name of the highlight group to use
-                    {line}       Line to highlight
+                    {line}       Line to highlight (zero-indexed)
                     {col_start}  Start of range of columns to highlight
                     {col_end}    End of range of columns to highlight, or -1
                                  to highlight to end of line
@@ -948,4 +968,4 @@ nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
 nvim_ui_set_option({name}, {value})                     *nvim_ui_set_option()*
                 TODO: Documentation
 
- vim:tw=78:ts=8:ft=help:norl:
+ vim:tw=78:ts=8:ft=help:norl:
\ No newline at end of file
diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py
index 8bc32d938f..51e585a007 100644
--- a/scripts/gen_api_vimdoc.py
+++ b/scripts/gen_api_vimdoc.py
@@ -73,7 +73,7 @@ text_width = 78
 script_path = os.path.abspath(__file__)
 base_dir = os.path.dirname(os.path.dirname(script_path))
 src_dir = os.path.join(base_dir, 'src/nvim/api')
-out_dir = os.path.join(base_dir, 'tmp/api_doc')
+out_dir = os.path.join(base_dir, 'tmp-api-doc')
 filter_cmd = '%s %s' % (sys.executable, script_path)
 seen_funcs = set()
 
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index f592f44f0e..4b6a88e5fa 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -439,6 +439,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
 /// Gets a changed tick of a buffer
 ///
 /// @param[in]  buffer  Buffer handle.
+/// @param[out] err     Error details, if any
 ///
 /// @return `b:changedtick` value.
 Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
@@ -453,14 +454,14 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
   return buf->b_changedtick;
 }
 
-/// Get a list of dictionaries describing buffer-local mappings
-/// Note that the buffer key in the dictionary will represent the buffer
-/// handle where the mapping is present
+/// Gets a list of dictionaries describing buffer-local mappings.
+/// The "buffer" key in the returned dictionary reflects the buffer
+/// handle where the mapping is present.
 ///
-/// @param  mode  The abbreviation for the mode
-/// @param  buffer_id  Buffer handle
+/// @param  mode       Mode short-name ("n", "i", "v", ...)
+/// @param  buffer     Buffer handle
 /// @param[out]  err   Error details, if any
-/// @returns An array of maparg() like dictionaries describing mappings
+/// @returns Array of maparg()-like dictionaries describing mappings
 ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
     FUNC_API_SINCE(3)
 {
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 86f4a9d008..e5ec018795 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -168,8 +168,8 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
 /// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call
 /// is not deferred. This is the most reliable way to send real user input.
 ///
-/// @note |keycodes| like <CR> are translated, so `<` is special.
-///       To input a literal `<`, send `<LT>`.
+/// @note |keycodes| like <CR> are translated, so "<" is special.
+///       To input a literal "<", send <LT>.
 ///
 /// @param keys to be typed
 /// @return Number of bytes actually written (can be fewer than
@@ -323,15 +323,15 @@ Object nvim_execute_lua(String code, Array args, Error *err)
 /// @param text       Some text
 /// @param[out] err   Error details, if any
 /// @return Number of cells
-Integer nvim_strwidth(String str, Error *err)
+Integer nvim_strwidth(String text, Error *err)
   FUNC_API_SINCE(1)
 {
-  if (str.size > INT_MAX) {
+  if (text.size > INT_MAX) {
     api_set_error(err, kErrorTypeValidation, "String length is too high");
     return 0;
   }
 
-  return (Integer) mb_string2cells((char_u *) str.data);
+  return (Integer)mb_string2cells((char_u *)text.data);
 }
 
 /// Gets the paths contained in 'runtimepath'.
@@ -581,7 +581,7 @@ Buffer nvim_get_current_buf(void)
 
 /// Sets the current buffer
 ///
-/// @param id       Buffer handle
+/// @param buffer   Buffer handle
 /// @param[out] err Error details, if any
 void nvim_set_current_buf(Buffer buffer, Error *err)
   FUNC_API_SINCE(1)
@@ -635,7 +635,7 @@ Window nvim_get_current_win(void)
 
 /// Sets the current window
 ///
-/// @param handle Window handle
+/// @param window Window handle
 void nvim_set_current_win(Window window, Error *err)
   FUNC_API_SINCE(1)
 {
@@ -688,7 +688,7 @@ Tabpage nvim_get_current_tabpage(void)
 
 /// Sets the current tabpage
 ///
-/// @param handle   Tabpage handle
+/// @param tabpage  Tabpage handle
 /// @param[out] err Error details, if any
 void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
   FUNC_API_SINCE(1)
@@ -758,9 +758,8 @@ Dictionary nvim_get_color_map(void)
 }
 
 
-/// Gets the current mode.
-/// mode:     Mode string. |mode()|
-/// blocking: true if Nvim is waiting for input.
+/// Gets the current mode. |mode()|
+/// "blocking" is true if Nvim is waiting for input.
 ///
 /// @returns Dictionary { "mode": String, "blocking": Boolean }
 Dictionary nvim_get_mode(void)
@@ -776,11 +775,11 @@ Dictionary nvim_get_mode(void)
   return rv;
 }
 
-/// Get a list of dictionaries describing global (i.e. non-buffer) mappings
-/// Note that the "buffer" key will be 0 to represent false.
+/// Gets a list of dictionaries describing global (non-buffer) mappings.
+/// The "buffer" key in the returned dictionary is always zero.
 ///
-/// @param  mode  The abbreviation for the mode
-/// @returns  An array of maparg() like dictionaries describing mappings
+/// @param  mode       Mode short-name ("n", "i", "v", ...)
+/// @returns Array of maparg()-like dictionaries describing mappings
 ArrayOf(Dictionary) nvim_get_keymap(String mode)
     FUNC_API_SINCE(3)
 {