docs: small fixes (#27213)

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

8 files changed, 24 insertions, 26 deletions

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