docs: various fixes (#27063)

Co-authored-by: lmenou <menl94629@gmail.com>
Co-authored-by: altermo <107814000+altermo@users.noreply.github.com>
Co-authored-by: VanaIgr <vanaigranov@gmail.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>

6 files changed, 33 insertions, 31 deletions

diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 37fded85cd..22c208426c 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -11550,7 +11550,7 @@ M.funcs = {
     ]=],
     name = 'synconcealed',
     params = { { 'lnum', 'integer' }, { 'col', 'integer' } },
-    returns = '{[1]: integer, [2]: string, [3]: integer}[]',
+    returns = '{[1]: integer, [2]: string, [3]: integer}',
     signature = 'synconcealed({lnum}, {col})',
   },
   synstack = {
diff --git a/src/nvim/ex_cmds.c b/src/nvim/ex_cmds.c
index 9a04b941ab..373ff8feda 100644
--- a/src/nvim/ex_cmds.c
+++ b/src/nvim/ex_cmds.c
@@ -3274,7 +3274,7 @@ static int check_regexp_delim(int c)
 ///
 /// @param cmdpreview_ns  The namespace to show 'inccommand' preview highlights.
 ///                       If <= 0, preview shouldn't be shown.
-/// @return 0, 1 or 2. See show_cmdpreview() for more information on what the return value means.
+/// @return  0, 1 or 2. See cmdpreview_may_show() for more information on the meaning.
 static int do_sub(exarg_T *eap, const proftime_T timeout, const int cmdpreview_ns,
                   const handle_T cmdpreview_bufnr)
 {
diff --git a/src/nvim/highlight.c b/src/nvim/highlight.c
index 47a87b90c3..17d743784f 100644
--- a/src/nvim/highlight.c
+++ b/src/nvim/highlight.c
@@ -484,7 +484,7 @@ int hl_get_underline(void)
   });
 }
 
-/// Augment an existing attribute with the beginning or end of a URL hyperlink.
+/// Augment an existing attribute with a URL.
 ///
 /// @param attr Existing attribute to combine with
 /// @param url The URL to associate with the highlight attribute
@@ -646,7 +646,6 @@ int hl_combine_attr(int char_attr, int prim_attr)
   }
 
   if ((new_en.url == -1) && (prim_aep.url >= 0)) {
-    // Combined attributes borrow the string from the primary attribute
     new_en.url = prim_aep.url;
   }
 
diff --git a/src/nvim/plines.c b/src/nvim/plines.c
index 631c847898..87eec8d22d 100644
--- a/src/nvim/plines.c
+++ b/src/nvim/plines.c
@@ -35,14 +35,14 @@
 
 /// Functions calculating horizontal size of text, when displayed in a window.
 
-/// Return the number of characters 'c' will take on the screen, taking
-/// into account the size of a tab.
+/// Return the number of cells the first char in "p" will take on the screen,
+/// taking into account the size of a tab.
 /// Also see getvcol()
 ///
 /// @param p
 /// @param col
 ///
-/// @return Number of characters.
+/// @return Number of cells.
 int win_chartabsize(win_T *wp, char *p, colnr_T col)
 {
   buf_T *buf = wp->w_buffer;
@@ -57,7 +57,7 @@ int win_chartabsize(win_T *wp, char *p, colnr_T col)
 /// @param startcol
 /// @param s
 ///
-/// @return Number of characters the string will take on the screen.
+/// @return Number of cells the string will take on the screen.
 int linetabsize_col(int startvcol, char *s)
 {
   CharsizeArg csarg;
@@ -107,14 +107,13 @@ CSType init_charsize_arg(CharsizeArg *csarg, win_T *wp, linenr_T lnum, char *lin
   }
 }
 
-/// Get the number of characters taken up on the screen for the given cts and position.
-/// "cts->cur_text_width_left" and "cts->cur_text_width_right" are set
+/// Get the number of cells taken up on the screen for the given arguments.
+/// "csarg->cur_text_width_left" and "csarg->cur_text_width_right" are set
 /// to the extra size for inline virtual text.
-/// This function is used very often, keep it fast!!!!
 ///
-/// When "cts->max_head_vcol" is positive, only count in "head" the size
-/// of 'showbreak'/'breakindent' before "cts->max_head_vcol".
-/// When "cts->max_head_vcol" is negative, only count in "head" the size
+/// When "csarg->max_head_vcol" is positive, only count in "head" the size
+/// of 'showbreak'/'breakindent' before "csarg->max_head_vcol".
+/// When "csarg->max_head_vcol" is negative, only count in "head" the size
 /// of 'showbreak'/'breakindent' before where cursor should be placed.
 CharSize charsize_regular(CharsizeArg *csarg, char *const cur, colnr_T const vcol,
                           int32_t const cur_char)
@@ -326,8 +325,9 @@ CharSize charsize_regular(CharsizeArg *csarg, char *const cur, colnr_T const vco
   return (CharSize){ .width = size, .head = head };
 }
 
-/// Like charsize_regular(), except it doesn't handle virtual text,
-/// linebreak, breakindent and showbreak. Handles normal characters, tabs and wrapping.
+/// Like charsize_regular(), except it doesn't handle inline virtual text,
+/// 'linebreak', 'breakindent' or 'showbreak'.
+/// Handles normal characters, tabs and wrapping.
 /// This function is always inlined.
 ///
 /// @see charsize_regular
@@ -360,9 +360,12 @@ static inline CharSize charsize_fast_impl(win_T *const wp, bool use_tabstop, col
   }
 }
 
-/// Like charsize_regular(), except it doesn't handle virtual text,
-/// linebreak, breakindent and showbreak. Handles normal characters, tabs and wrapping.
+/// Like charsize_regular(), except it doesn't handle inline virtual text,
+/// 'linebreak', 'breakindent' or 'showbreak'.
+/// Handles normal characters, tabs and wrapping.
 /// Can be used if CSType is kCharsizeFast.
+///
+/// @see charsize_regular
 CharSize charsize_fast(CharsizeArg *csarg, colnr_T const vcol, int32_t const cur_char)
   FUNC_ATTR_PURE
 {
@@ -397,14 +400,14 @@ static bool in_win_border(win_T *wp, colnr_T vcol)
   return (vcol - width1) % width2 == width2 - 1;
 }
 
-/// Calculate virtual column until the given 'len'.
+/// Calculate virtual column until the given "len".
 ///
 /// @param arg  Argument to charsize functions.
 /// @param vcol Starting virtual column.
 /// @param len  First byte of the end character, or MAXCOL.
 ///
-/// @return virtual column before the character at 'len',
-/// or full size of the line if 'len' is MAXCOL.
+/// @return virtual column before the character at "len",
+/// or full size of the line if "len" is MAXCOL.
 int linesize_regular(CharsizeArg *const csarg, int vcol, colnr_T const len)
 {
   char *const line = csarg->line;
@@ -424,9 +427,9 @@ int linesize_regular(CharsizeArg *const csarg, int vcol, colnr_T const len)
   return vcol;
 }
 
-/// Like win_linesize_regular, but can be used when CStype is kCharsizeFast.
+/// Like linesize_regular(), but can be used when CStype is kCharsizeFast.
 ///
-/// @see win_linesize_regular
+/// @see linesize_regular
 int linesize_fast(CharsizeArg const *const csarg, int vcol, colnr_T const len)
 {
   win_T *const wp = csarg->win;
diff --git a/src/nvim/plines.h b/src/nvim/plines.h
index a4c5ced15a..30d3f671fa 100644
--- a/src/nvim/plines.h
+++ b/src/nvim/plines.h
@@ -46,12 +46,12 @@ static inline CharSize win_charsize(CSType cstype, int vcol, char *ptr, int32_t
   REAL_FATTR_NONNULL_ALL REAL_FATTR_WARN_UNUSED_RESULT REAL_FATTR_ALWAYS_INLINE;
 
 /// Get the number of cells taken up on the screen by the given character at vcol.
-/// "arg->cur_text_width_left" and "arg->cur_text_width_right" are set
+/// "csarg->cur_text_width_left" and "csarg->cur_text_width_right" are set
 /// to the extra size for inline virtual text.
 ///
-/// When "arg->max_head_vcol" is positive, only count in "head" the size
-/// of 'showbreak'/'breakindent' before "arg->max_head_vcol".
-/// When "arg->max_head_vcol" is negative, only count in "head" the size
+/// When "csarg->max_head_vcol" is positive, only count in "head" the size
+/// of 'showbreak'/'breakindent' before "csarg->max_head_vcol".
+/// When "csarg->max_head_vcol" is negative, only count in "head" the size
 /// of 'showbreak'/'breakindent' before where cursor should be placed.
 static inline CharSize win_charsize(CSType cstype, int vcol, char *ptr, int32_t chr,
                                     CharsizeArg *csarg)
@@ -66,12 +66,12 @@ static inline CharSize win_charsize(CSType cstype, int vcol, char *ptr, int32_t
 static inline int linetabsize_str(char *s)
   REAL_FATTR_NONNULL_ALL REAL_FATTR_WARN_UNUSED_RESULT REAL_FATTR_ALWAYS_INLINE;
 
-/// Return the number of characters the string 's' will take on the screen,
+/// Return the number of cells the string "s" will take on the screen,
 /// taking into account the size of a tab.
 ///
 /// @param s
 ///
-/// @return Number of characters the string will take on the screen.
+/// @return Number of cells the string will take on the screen.
 static inline int linetabsize_str(char *s)
 {
   return linetabsize_col(0, s);
@@ -86,7 +86,7 @@ static inline int win_linetabsize(win_T *wp, linenr_T lnum, char *line, colnr_T
 /// @param line
 /// @param len
 ///
-/// @return Number of characters the string will take on the screen.
+/// @return Number of cells the string will take on the screen.
 static inline int win_linetabsize(win_T *wp, linenr_T lnum, char *line, colnr_T len)
 {
   CharsizeArg csarg;
diff --git a/src/nvim/textformat.c b/src/nvim/textformat.c
index e1b6d3acc9..6fa60239a2 100644
--- a/src/nvim/textformat.c
+++ b/src/nvim/textformat.c
@@ -81,7 +81,7 @@ void internal_format(int textwidth, int second_indent, int flags, bool format_on
   bool do_comments = (flags & INSCHAR_DO_COM);
   int has_lbr = curwin->w_p_lbr;
 
-  // make sure win_lbr_chartabsize() counts correctly
+  // make sure win_charsize() counts correctly
   curwin->w_p_lbr = false;
 
   // When 'ai' is off we don't want a space under the cursor to be