docs: small fixes (#27213)

Co-authored-by: Matthieu Coudron <886074+teto@users.noreply.github.com>

12 files changed, 36 insertions, 39 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index c1fc04d9cf..3dc85eddbb 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -104,10 +104,10 @@ The following changes may require adaptations in user config or plugins.
   • |hl-WinSeparator| is linked to |hl-Normal| instead of |hl-VertSplit|.
 
   This also might result into some color schemes looking differently due to
-  them relying on an implicit assumptions about how highlight groups are
-  defined by default. To account for this, define all attributes of highlight
-  groups explicitly. Alternatively, use `:colorscheme vim` or
-  `:source $VIMRUNTIME/colors/vim.lua` to restore previous definitions.
+  them relying on implicit assumptions about how highlight groups are defined
+  by default. To account for this, define all attributes of highlight groups
+  explicitly. Alternatively, use `:colorscheme vim` or `:source
+  $VIMRUNTIME/colors/vim.lua` to restore previous definitions.
 
 • 'termguicolors' is enabled by default when Nvim is able to determine that
   the host terminal emulator supports 24-bit color.
@@ -125,7 +125,6 @@ unreleased features on Nvim HEAD.
 
 • Removed `vim.treesitter.foldtext` as transparent foldtext is now supported
   https://github.com/neovim/neovim/pull/20750
-• ...
 
 ==============================================================================
 NEW FEATURES                                                    *news-features*
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index a3a2422ab5..ec465f4780 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -1023,7 +1023,7 @@ end
 
 --- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts
 --- @field cursor_position? {[1]:integer,[2]:integer}
---- @field wrap? integer
+--- @field wrap? boolean
 --- @field float? boolean|vim.diagnostic.Opts.Float
 --- @field win_id? integer
 
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 2dc817c5c1..038aa8acfb 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -10,14 +10,14 @@ local tohex = require('bit').tohex
 local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9.+-]*):.*'
 local WINDOWS_URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9.+-]*):[a-zA-Z]:.*'
 local PATTERNS = {
-  ---RFC 2396
-  ---https://tools.ietf.org/html/rfc2396#section-2.2
+  -- RFC 2396
+  -- https://tools.ietf.org/html/rfc2396#section-2.2
   rfc2396 = "^A-Za-z0-9%-_.!~*'()",
-  ---RFC 2732
-  ---https://tools.ietf.org/html/rfc2732
+  -- RFC 2732
+  -- https://tools.ietf.org/html/rfc2732
   rfc2732 = "^A-Za-z0-9%-_.!~*'()[]",
-  ---RFC 3986
-  ---https://tools.ietf.org/html/rfc3986#section-2.2
+  -- RFC 3986
+  -- https://tools.ietf.org/html/rfc3986#section-2.2
   rfc3986 = "^A-Za-z0-9%-._~!$&'()*+,;=:@/",
 }
 
diff --git a/src/nvim/drawscreen.c b/src/nvim/drawscreen.c
index 5c33eb745b..4b7dd40616 100644
--- a/src/nvim/drawscreen.c
+++ b/src/nvim/drawscreen.c
@@ -159,8 +159,8 @@ void conceal_check_cursor_line(void)
 /// There may be some time between setting Rows and Columns and (re)allocating
 /// default_grid arrays.  This happens when starting up and when
 /// (manually) changing the screen size.  Always use default_grid.rows and
-/// default_grid.Columns to access items in default_grid.chars[].  Use Rows
-/// and Columns for positioning text etc. where the final size of the screen is
+/// default_grid.cols to access items in default_grid.chars[].  Use Rows and
+/// Columns for positioning text etc. where the final size of the screen is
 /// needed.
 ///
 /// @return  whether resizing has been done
diff --git a/src/nvim/input.c b/src/nvim/input.c
index 7e6b6d4bd0..7667c49452 100644
--- a/src/nvim/input.c
+++ b/src/nvim/input.c
@@ -35,7 +35,7 @@
 /// @param[in]  str  Prompt: question to ask user. Is always followed by
 ///                  " (y/n)?".
 /// @param[in]  direct  Determines what function to use to get user input. If
-///                     true then ui_inchar() will be used, otherwise vgetc().
+///                     true then os_inchar() will be used, otherwise vgetc().
 ///                     I.e. when direct is true then characters are obtained
 ///                     directly from the user without buffers involved.
 ///
diff --git a/src/nvim/mbyte.c b/src/nvim/mbyte.c
index b1f7b59b21..c0ba1d9e9b 100644
--- a/src/nvim/mbyte.c
+++ b/src/nvim/mbyte.c
@@ -534,7 +534,7 @@ int utf_ptr2cells(const char *p)
 /// @param[in]  p      String to convert.
 /// @param[in]  len    Length of the character in bytes, 0 or 1 if illegal.
 ///
-/// @return Unicode codepoint. A negative value When the sequence is illegal.
+/// @return Unicode codepoint. A negative value when the sequence is illegal.
 int32_t utf_ptr2CharInfo_impl(uint8_t const *p, uintptr_t const len)
   FUNC_ATTR_PURE FUNC_ATTR_NONNULL_ALL FUNC_ATTR_WARN_UNUSED_RESULT
 {
diff --git a/src/nvim/mbyte.h b/src/nvim/mbyte.h
index 2603f0df55..2f17c706c1 100644
--- a/src/nvim/mbyte.h
+++ b/src/nvim/mbyte.h
@@ -61,7 +61,7 @@ static inline CharInfo utf_ptr2CharInfo(char const *p_in)
 /// @param[in]  p_in  String to convert.
 ///
 /// @return information abouth the character. When the sequence is illegal,
-/// 'value' is negative, 'len' is 1.
+/// "value" is negative, "len" is 1.
 static inline CharInfo utf_ptr2CharInfo(char const *const p_in)
 {
   uint8_t const *const p = (uint8_t const *)p_in;
@@ -82,11 +82,9 @@ static inline StrCharInfo utfc_next(StrCharInfo cur)
   REAL_FATTR_NONNULL_ALL REAL_FATTR_ALWAYS_INLINE REAL_FATTR_PURE;
 
 /// Return information about the next character.
-/// Composing and combining characters are
-/// considered a part of the current character.
+/// Composing and combining characters are considered a part of the current character.
 ///
-/// @param[in] cur  Pointer to the current character. Must not point to NUL
-/// @param[in] cur_char Decoded charater at 'cur'.
+/// @param[in] cur  Information about the current character in the string.
 static inline StrCharInfo utfc_next(StrCharInfo cur)
 {
   int32_t prev_code = cur.chr.value;
diff --git a/src/nvim/mbyte_defs.h b/src/nvim/mbyte_defs.h
index 97aa1a638b..058ec353e5 100644
--- a/src/nvim/mbyte_defs.h
+++ b/src/nvim/mbyte_defs.h
@@ -58,11 +58,11 @@ typedef struct {
 } vimconv_T;
 
 typedef struct {
-  int32_t value;  ///< code point
-  int len;        ///< length in bytes
+  int32_t value;  ///< Code point.
+  int len;        ///< Length in bytes.
 } CharInfo;
 
 typedef struct {
-  char *ptr;     ///< pointer to the first byte of the character
-  CharInfo chr;  ///< the character
+  char *ptr;     ///< Pointer to the first byte of the character.
+  CharInfo chr;  ///< Information about the character.
 } StrCharInfo;
diff --git a/src/nvim/message.c b/src/nvim/message.c
index 9dd83d6c02..cb89d34e23 100644
--- a/src/nvim/message.c
+++ b/src/nvim/message.c
@@ -129,7 +129,7 @@ bool keep_msg_more = false;    // keep_msg was set by msgmore()
 //                  Set: When the ruler or typeahead display is overwritten,
 //                  scrolling the screen for some message.
 // keep_msg         Message to be displayed after redrawing the screen, in
-//                  main_loop().
+//                  Normal mode main loop.
 //                  This is an allocated string or NULL when not used.
 
 // Extended msg state, currently used for external UIs with ext_messages
diff --git a/src/nvim/os/input.c b/src/nvim/os/input.c
index abba49f0e8..fab360c9af 100644
--- a/src/nvim/os/input.c
+++ b/src/nvim/os/input.c
@@ -95,7 +95,7 @@ static void cursorhold_event(void **argv)
 static void create_cursorhold_event(bool events_enabled)
 {
   // If events are enabled and the queue has any items, this function should not
-  // have been called(inbuf_poll would return kInputAvail)
+  // have been called (inbuf_poll would return kInputAvail).
   // TODO(tarruda): Cursorhold should be implemented as a timer set during the
   // `state_check` callback for the states where it can be triggered.
   assert(!events_enabled || multiqueue_empty(main_loop.events));
@@ -110,7 +110,7 @@ static void restart_cursorhold_wait(int tb_change_cnt)
 
 /// Low level input function
 ///
-/// wait until either the input buffer is non-empty or, if `events` is not NULL
+/// Wait until either the input buffer is non-empty or, if `events` is not NULL
 /// until `events` is non-empty.
 int os_inchar(uint8_t *buf, int maxlen, int ms, int tb_change_cnt, MultiQueue *events)
 {
@@ -543,7 +543,7 @@ bool os_input_ready(MultiQueue *events)
 {
   return (typebuf_was_filled             // API call filled typeahead
           || rbuffer_size(input_buffer)  // Input buffer filled
-          || pending_events(events));          // Events must be processed
+          || pending_events(events));    // Events must be processed
 }
 
 // Exit because of an input read error.
diff --git a/src/nvim/plines.h b/src/nvim/plines.h
index 461e79e3ad..658206e1be 100644
--- a/src/nvim/plines.h
+++ b/src/nvim/plines.h
@@ -18,23 +18,23 @@ enum {
 /// Argument for char size functions.
 typedef struct {
   win_T *win;
-  char *line;                ///< start of the line
+  char *line;                ///< Start of the line.
 
-  bool use_tabstop;          ///< use tabstop for tab insted of counting it as ^I
-  int indent_width;          ///< width of showbreak and breakindent on wrapped lines
-                             ///  INT_MIN if not yet calculated
+  bool use_tabstop;          ///< Use 'tabstop' instead of char2cells() for a TAB.
+  int indent_width;          ///< Width of 'showbreak' and 'breakindent' on wrapped
+                             ///< parts of lines, INT_MIN if not yet calculated.
 
-  int virt_row;              ///< line number, -1 if no virtual text
-  int cur_text_width_left;   ///< width of virtual text left of cursor
-  int cur_text_width_right;  ///< width of virtual text right of cursor
+  int virt_row;              ///< Row for virtual text, -1 if no virtual text.
+  int cur_text_width_left;   ///< Width of virtual text left of cursor.
+  int cur_text_width_right;  ///< Width of virtual text right of cursor.
 
-  int max_head_vcol;         ///< see charsize_regular()
+  int max_head_vcol;         ///< See charsize_regular().
   MarkTreeIter iter[1];
 } CharsizeArg;
 
 typedef struct {
   int width;
-  int head;  // size of breakindent etc. before the character (included in width)
+  int head;  ///< Size of 'breakindent' etc. before the character (included in width).
 } CharSize;
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
diff --git a/test/functional/ui/highlight_spec.lua b/test/functional/ui/highlight_spec.lua
index af6ae5bf46..2ec10d149f 100644
--- a/test/functional/ui/highlight_spec.lua
+++ b/test/functional/ui/highlight_spec.lua
@@ -31,7 +31,7 @@ describe('highlight: `:syntax manual`', function()
     clear()
     screen = Screen.new(20, 5)
     screen:attach()
-    --syntax highlight for vimcscripts "echo"
+    -- syntax highlight for vimscript's "echo"
     screen:set_default_attr_ids({
       [0] = { bold = true, foreground = Screen.colors.Blue },
       [1] = { bold = true, foreground = Screen.colors.Brown },