Merge pull request #17719 from dundargoc/doxygen/ex_docmd

refactor(ex_docmd): convert function comments to doxygen format

1 files changed, 244 insertions, 426 deletions

diff --git a/src/nvim/ex_docmd.c b/src/nvim/ex_docmd.c
index c6089562f3..511dd44c9f 100644
--- a/src/nvim/ex_docmd.c
+++ b/src/nvim/ex_docmd.c
@@ -250,8 +250,9 @@ void do_exmode(void)
   msg_scroll = save_msg_scroll;
 }
 
-// Print the executed command for when 'verbose' is set.
-// When "lnum" is 0 only print the command.
+/// Print the executed command for when 'verbose' is set.
+///
+/// @param lnum  if 0, only print the command.
 static void msg_verbose_cmd(linenr_T lnum, char_u *cmd)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -271,9 +272,7 @@ static void msg_verbose_cmd(linenr_T lnum, char_u *cmd)
   no_wait_return--;
 }
 
-/*
- * Execute a simple command line.  Used for translated commands like "*".
- */
+/// Execute a simple command line.  Used for translated commands like "*".
 int do_cmdline_cmd(const char *cmd)
 {
   return do_cmdline((char_u *)cmd, NULL, NULL,
@@ -952,9 +951,7 @@ int do_cmdline(char_u *cmdline, LineGetter fgetline, void *cookie, int flags)
   return retval;
 }
 
-/*
- * Obtain a line when inside a ":while" or ":for" loop.
- */
+/// Obtain a line when inside a ":while" or ":for" loop.
 static char_u *get_loop_line(int c, void *cookie, int indent, bool do_concat)
 {
   struct loop_cookie *cp = (struct loop_cookie *)cookie;
@@ -986,9 +983,7 @@ static char_u *get_loop_line(int c, void *cookie, int indent, bool do_concat)
   return vim_strsave(wp->line);
 }
 
-/*
- * Store a line in "gap" so that a ":while" loop can execute it again.
- */
+/// Store a line in "gap" so that a ":while" loop can execute it again.
 static void store_loop_line(garray_T *gap, char_u *line)
 {
   wcmd_T *p = GA_APPEND_VIA_PTR(wcmd_T, gap);
@@ -1038,11 +1033,10 @@ void *getline_cookie(LineGetter fgetline, void *cookie)
   return cp;
 }
 
-/*
- * Helper function to apply an offset for buffer commands, i.e. ":bdelete",
- * ":bwipeout", etc.
- * Returns the buffer number.
- */
+/// Helper function to apply an offset for buffer commands, i.e. ":bdelete",
+/// ":bwipeout", etc.
+///
+/// @return  the buffer number.
 static int compute_buffer_local_count(int addr_type, int lnum, int offset)
 {
   buf_T *buf;
@@ -1084,8 +1078,8 @@ static int compute_buffer_local_count(int addr_type, int lnum, int offset)
   return buf->b_fnum;
 }
 
-// Return the window number of "win".
-// When "win" is NULL return the number of windows.
+/// @return  the window number of "win" or,
+///          the number of windows if "win" is NULL
 static int current_win_nr(const win_T *win)
   FUNC_ATTR_PURE FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -2049,18 +2043,20 @@ char *ex_errmsg(const char *const msg, const char_u *const arg)
   return ex_error_buf;
 }
 
-// Parse and skip over command modifiers:
-// - update eap->cmd
-// - store flags in "cmdmod".
-// - Set ex_pressedreturn for an empty command line.
-// - set msg_silent for ":silent"
-// - set 'eventignore' to "all" for ":noautocmd"
-// - set p_verbose for ":verbose"
-// - Increment "sandbox" for ":sandbox"
-// When "skip_only" is true the global variables are not changed, except for
-// "cmdmod".
-// Return FAIL when the command is not to be executed.
-// May set "errormsg" to an error message.
+/// Parse and skip over command modifiers:
+/// - update eap->cmd
+/// - store flags in "cmdmod".
+/// - Set ex_pressedreturn for an empty command line.
+/// - set msg_silent for ":silent"
+/// - set 'eventignore' to "all" for ":noautocmd"
+/// - set p_verbose for ":verbose"
+/// - Increment "sandbox" for ":sandbox"
+///
+/// @param skip_only      if true, the global variables are not changed, except for
+///                       "cmdmod".
+/// @param[out] errormsg  potential error message.
+///
+/// @return  FAIL when the command is not to be executed.
 int parse_command_modifiers(exarg_T *eap, char **errormsg, bool skip_only)
 {
   char_u *p;
@@ -2319,7 +2315,7 @@ int parse_command_modifiers(exarg_T *eap, char **errormsg, bool skip_only)
   return OK;
 }
 
-// Undo and free contents of "cmdmod".
+/// Undo and free contents of "cmdmod".
 static void undo_cmdmod(const exarg_T *eap, int save_msg_scroll)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -2358,9 +2354,10 @@ static void undo_cmdmod(const exarg_T *eap, int save_msg_scroll)
 }
 
 
-// Parse the address range, if any, in "eap".
-// May set the last search pattern, unless "silent" is true.
-// Return FAIL and set "errormsg" or return OK.
+/// Parse the address range, if any, in "eap".
+/// May set the last search pattern, unless "silent" is true.
+///
+/// @return  FAIL and set "errormsg" or return OK.
 int parse_cmd_address(exarg_T *eap, char **errormsg, bool silent)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -2552,11 +2549,9 @@ int checkforcmd(char_u **pp, char *cmd, int len)
   return FALSE;
 }
 
-/*
- * Append "cmd" to the error message in IObuff.
- * Takes care of limiting the length and handling 0xa0, which would be
- * invisible otherwise.
- */
+/// Append "cmd" to the error message in IObuff.
+/// Takes care of limiting the length and handling 0xa0, which would be
+/// invisible otherwise.
 static void append_command(char_u *cmd)
 {
   char_u *s = cmd;
@@ -2576,11 +2571,12 @@ static void append_command(char_u *cmd)
   *d = NUL;
 }
 
-// Find an Ex command by its name, either built-in or user.
-// Start of the name can be found at eap->cmd.
-// Sets eap->cmdidx and returns a pointer to char after the command name.
-// "full" is set to TRUE if the whole command name matched.
-// Returns NULL for an ambiguous user command.
+/// Find an Ex command by its name, either built-in or user.
+/// Start of the name can be found at eap->cmd.
+/// Sets eap->cmdidx and returns a pointer to char after the command name.
+/// "full" is set to TRUE if the whole command name matched.
+///
+/// @return  NULL for an ambiguous user command.
 static char_u *find_command(exarg_T *eap, int *full)
   FUNC_ATTR_NONNULL_ARG(1)
 {
@@ -2834,10 +2830,8 @@ static struct cmdmod {
   { "vertical", 4, false },
 };
 
-/*
- * Return length of a command modifier (including optional count).
- * Return zero when it's not a modifier.
- */
+/// @return  length of a command modifier (including optional count) or,
+///          zero when it's not a modifier.
 int modifier_len(char_u *cmd)
 {
   char_u *p = cmd;
@@ -2861,11 +2855,9 @@ int modifier_len(char_u *cmd)
   return 0;
 }
 
-/*
- * Return > 0 if an Ex command "name" exists.
- * Return 2 if there is an exact match.
- * Return 3 if there is an ambiguous match.
- */
+/// @return  > 0 if an Ex command "name" exists or,
+///            2 if there is an exact match or,
+///            3 if there is an ambiguous match.
 int cmd_exists(const char *const name)
 {
   exarg_T ea;
@@ -2902,7 +2894,7 @@ int cmd_exists(const char *const name)
   return ea.cmdidx == CMD_SIZE ? 0 : (full ? 2 : 1);
 }
 
-// "fullcommand" function
+/// "fullcommand" function
 void f_fullcommand(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   exarg_T ea;
@@ -4192,9 +4184,7 @@ error:
   return lnum;
 }
 
-/*
- * Get flags from an Ex command argument.
- */
+/// Get flags from an Ex command argument.
 static void get_flags(exarg_T *eap)
 {
   while (vim_strchr((char_u *)"lp#", *eap->arg) != NULL) {
@@ -4229,10 +4219,9 @@ static void ex_script_ni(exarg_T *eap)
   }
 }
 
-/*
- * Check range in Ex command for validity.
- * Return NULL when valid, error message when invalid.
- */
+/// Check range in Ex command for validity.
+///
+/// @return  NULL when valid, error message when invalid.
 static char *invalid_range(exarg_T *eap)
 {
   buf_T *buf;
@@ -4318,9 +4307,7 @@ static char *invalid_range(exarg_T *eap)
   return NULL;
 }
 
-/*
- * Correct the range for zero line number, if required.
- */
+/// Correct the range for zero line number, if required.
 static void correct_range(exarg_T *eap)
 {
   if (!(eap->argt & EX_ZEROR)) {  // zero in range not allowed
@@ -4334,10 +4321,8 @@ static void correct_range(exarg_T *eap)
 }
 
 
-/*
- * For a ":vimgrep" or ":vimgrepadd" command return a pointer past the
- * pattern.  Otherwise return eap->arg.
- */
+/// For a ":vimgrep" or ":vimgrepadd" command return a pointer past the
+/// pattern.  Otherwise return eap->arg.
 static char_u *skip_grep_pat(exarg_T *eap)
 {
   char_u *p = eap->arg;
@@ -4354,10 +4339,8 @@ static char_u *skip_grep_pat(exarg_T *eap)
   return p;
 }
 
-/*
- * For the ":make" and ":grep" commands insert the 'makeprg'/'grepprg' option
- * in the command line, so that things like % get expanded.
- */
+/// For the ":make" and ":grep" commands insert the 'makeprg'/'grepprg' option
+/// in the command line, so that things like % get expanded.
 static char_u *replace_makeprg(exarg_T *eap, char_u *p, char_u **cmdlinep)
 {
   char_u *new_cmdline;
@@ -4425,9 +4408,10 @@ static char_u *replace_makeprg(exarg_T *eap, char_u *p, char_u **cmdlinep)
   return p;
 }
 
-// Expand file name in Ex command argument.
-// When an error is detected, "errormsgp" is set to a non-NULL pointer.
-// Return FAIL for failure, OK otherwise.
+/// Expand file name in Ex command argument.
+/// When an error is detected, "errormsgp" is set to a non-NULL pointer.
+///
+/// @return  FAIL for failure, OK otherwise.
 int expand_filename(exarg_T *eap, char_u **cmdlinep, char **errormsgp)
 {
   int has_wildcards;            // need to expand wildcards
@@ -4595,13 +4579,12 @@ int expand_filename(exarg_T *eap, char_u **cmdlinep, char **errormsgp)
   return OK;
 }
 
-/*
- * Replace part of the command line, keeping eap->cmd, eap->arg and
- * eap->nextcmd correct.
- * "src" points to the part that is to be replaced, of length "srclen".
- * "repl" is the replacement string.
- * Returns a pointer to the character after the replaced string.
- */
+/// Replace part of the command line, keeping eap->cmd, eap->arg and
+/// eap->nextcmd correct.
+/// "src" points to the part that is to be replaced, of length "srclen".
+/// "repl" is the replacement string.
+///
+/// @return  a pointer to the character after the replaced string.
 static char_u *repl_cmdline(exarg_T *eap, char_u *src, size_t srclen, char_u *repl,
                             char_u **cmdlinep)
 {
@@ -4647,9 +4630,7 @@ static char_u *repl_cmdline(exarg_T *eap, char_u *src, size_t srclen, char_u *re
   return src;
 }
 
-/*
- * Check for '|' to separate commands and '"' to start comments.
- */
+/// Check for '|' to separate commands and '"' to start comments.
 void separate_nextcmd(exarg_T *eap)
 {
   char_u *p;
@@ -4704,9 +4685,7 @@ void separate_nextcmd(exarg_T *eap)
   }
 }
 
-/*
- * get + command from ex argument
- */
+/// get + command from ex argument
 static char_u *getargcmd(char_u **argp)
 {
   char_u *arg = *argp;
@@ -4763,10 +4742,9 @@ int get_bad_opt(const char_u *p, exarg_T *eap)
   return OK;
 }
 
-/*
- * Get "++opt=arg" argument.
- * Return FAIL or OK.
- */
+/// Get "++opt=arg" argument.
+///
+/// @return  FAIL or OK.
 static int getargopt(exarg_T *eap)
 {
   char_u *arg = eap->arg + 2;
@@ -4846,8 +4824,9 @@ static int getargopt(exarg_T *eap)
 }
 
 /// Handle the argument for a tabpage related ex command.
-/// Returns a tabpage number.
 /// When an error is encountered then eap->errmsg is set.
+///
+/// @return  a tabpage number.
 static int get_tabpage_arg(exarg_T *eap)
 {
   int tab_number = 0;
@@ -4936,17 +4915,13 @@ theend:
   return tab_number;
 }
 
-/*
- * ":abbreviate" and friends.
- */
+/// ":abbreviate" and friends.
 static void ex_abbreviate(exarg_T *eap)
 {
   do_exmap(eap, TRUE);          // almost the same as mapping
 }
 
-/*
- * ":map" and friends.
- */
+/// ":map" and friends.
 static void ex_map(exarg_T *eap)
 {
   /*
@@ -4961,25 +4936,19 @@ static void ex_map(exarg_T *eap)
   do_exmap(eap, FALSE);
 }
 
-/*
- * ":unmap" and friends.
- */
+/// ":unmap" and friends.
 static void ex_unmap(exarg_T *eap)
 {
   do_exmap(eap, FALSE);
 }
 
-/*
- * ":mapclear" and friends.
- */
+/// ":mapclear" and friends.
 static void ex_mapclear(exarg_T *eap)
 {
   map_clear_mode(eap->cmd, eap->arg, eap->forceit, false);
 }
 
-/*
- * ":abclear" and friends.
- */
+/// ":abclear" and friends.
 static void ex_abclear(exarg_T *eap)
 {
   map_clear_mode(eap->cmd, eap->arg, true, true);
@@ -4999,9 +4968,7 @@ static void ex_autocmd(exarg_T *eap)
   }
 }
 
-/*
- * ":doautocmd": Apply the automatic commands to the current buffer.
- */
+/// ":doautocmd": Apply the automatic commands to the current buffer.
 static void ex_doautocmd(exarg_T *eap)
 {
   char_u *arg = eap->arg;
@@ -5015,11 +4982,9 @@ static void ex_doautocmd(exarg_T *eap)
   }
 }
 
-/*
- * :[N]bunload[!] [N] [bufname] unload buffer
- * :[N]bdelete[!] [N] [bufname] delete buffer from buffer list
- * :[N]bwipeout[!] [N] [bufname] delete buffer really
- */
+/// :[N]bunload[!] [N] [bufname] unload buffer
+/// :[N]bdelete[!] [N] [bufname] delete buffer from buffer list
+/// :[N]bwipeout[!] [N] [bufname] delete buffer really
 static void ex_bunload(exarg_T *eap)
 {
   eap->errmsg = do_bufdel(eap->cmdidx == CMD_bdelete ? DOBUF_DEL
@@ -5029,10 +4994,8 @@ static void ex_bunload(exarg_T *eap)
                           eap->addr_count, (int)eap->line1, (int)eap->line2, eap->forceit);
 }
 
-/*
- * :[N]buffer [N]       to buffer N
- * :[N]sbuffer [N]      to buffer N
- */
+/// :[N]buffer [N]       to buffer N
+/// :[N]sbuffer [N]      to buffer N
 static void ex_buffer(exarg_T *eap)
 {
   if (*eap->arg) {
@@ -5049,10 +5012,8 @@ static void ex_buffer(exarg_T *eap)
   }
 }
 
-/*
- * :[N]bmodified [N]    to next mod. buffer
- * :[N]sbmodified [N]   to next mod. buffer
- */
+/// :[N]bmodified [N]    to next mod. buffer
+/// :[N]sbmodified [N]   to next mod. buffer
 static void ex_bmodified(exarg_T *eap)
 {
   goto_buffer(eap, DOBUF_MOD, FORWARD, (int)eap->line2);
@@ -5061,10 +5022,8 @@ static void ex_bmodified(exarg_T *eap)
   }
 }
 
-/*
- * :[N]bnext [N]        to next buffer
- * :[N]sbnext [N]       split and to next buffer
- */
+/// :[N]bnext [N]        to next buffer
+/// :[N]sbnext [N]       split and to next buffer
 static void ex_bnext(exarg_T *eap)
 {
   goto_buffer(eap, DOBUF_CURRENT, FORWARD, (int)eap->line2);
@@ -5073,12 +5032,10 @@ static void ex_bnext(exarg_T *eap)
   }
 }
 
-/*
- * :[N]bNext [N]        to previous buffer
- * :[N]bprevious [N]    to previous buffer
- * :[N]sbNext [N]       split and to previous buffer
- * :[N]sbprevious [N]   split and to previous buffer
- */
+/// :[N]bNext [N]        to previous buffer
+/// :[N]bprevious [N]    to previous buffer
+/// :[N]sbNext [N]       split and to previous buffer
+/// :[N]sbprevious [N]   split and to previous buffer
 static void ex_bprevious(exarg_T *eap)
 {
   goto_buffer(eap, DOBUF_CURRENT, BACKWARD, (int)eap->line2);
@@ -5087,12 +5044,10 @@ static void ex_bprevious(exarg_T *eap)
   }
 }
 
-/*
- * :brewind             to first buffer
- * :bfirst              to first buffer
- * :sbrewind            split and to first buffer
- * :sbfirst             split and to first buffer
- */
+/// :brewind             to first buffer
+/// :bfirst              to first buffer
+/// :sbrewind            split and to first buffer
+/// :sbfirst             split and to first buffer
 static void ex_brewind(exarg_T *eap)
 {
   goto_buffer(eap, DOBUF_FIRST, FORWARD, 0);
@@ -5101,10 +5056,8 @@ static void ex_brewind(exarg_T *eap)
   }
 }
 
-/*
- * :blast               to last buffer
- * :sblast              split and to last buffer
- */
+/// :blast               to last buffer
+/// :sblast              split and to last buffer
 static void ex_blast(exarg_T *eap)
 {
   goto_buffer(eap, DOBUF_LAST, BACKWARD, 0);
@@ -5118,10 +5071,8 @@ int ends_excmd(int c) FUNC_ATTR_CONST
   return c == NUL || c == '|' || c == '"' || c == '\n';
 }
 
-/*
- * Return the next command, after the first '|' or '\n'.
- * Return NULL if not found.
- */
+/// @return  the next command, after the first '|' or '\n' or,
+///          NULL if not found.
 char_u *find_nextcmd(const char_u *p)
 {
   while (*p != '|' && *p != '\n') {
@@ -5134,7 +5085,8 @@ char_u *find_nextcmd(const char_u *p)
 }
 
 /// Check if *p is a separator between Ex commands, skipping over white space.
-/// Return NULL if it isn't, the following character if it is.
+///
+/// @return  NULL if it isn't, the following character if it is.
 char_u *check_nextcmd(char_u *p)
 {
   char_u *s = skipwhite(p);
@@ -5150,9 +5102,10 @@ char_u *check_nextcmd(char_u *p)
 /// - and this is the last window
 /// - and forceit not used
 /// - and not repeated twice on a row
-/// @return  FAIL and give error message if 'message' TRUE, return OK otherwise
 ///
 /// @param   message  when FALSE check only, no messages
+///
+/// @return  FAIL and give error message if 'message' TRUE, return OK otherwise
 static int check_more(int message, bool forceit)
 {
   int n = ARGCOUNT - curwin->w_arg_idx - 1;
@@ -5180,9 +5133,7 @@ static int check_more(int message, bool forceit)
   return OK;
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of command names.
- */
+/// Function given to ExpandGeneric() to obtain the list of command names.
 char_u *get_command_name(expand_T *xp, int idx)
 {
   if (idx >= CMD_SIZE) {
@@ -5693,9 +5644,7 @@ invalid_count:
 
 static char e_complete_used_without_nargs[] = N_("E1208: -complete used without -nargs");
 
-/*
- * ":command ..."
- */
+/// ":command ..."
 static void ex_command(exarg_T *eap)
 {
   char_u *name;
@@ -5749,10 +5698,8 @@ static void ex_command(exarg_T *eap)
   }
 }
 
-/*
- * ":comclear"
- * Clear all user commands, global and for current buffer.
- */
+/// ":comclear"
+/// Clear all user commands, global and for current buffer.
 void ex_comclear(exarg_T *eap)
 {
   uc_clear(&ucmds);
@@ -5768,9 +5715,7 @@ void free_ucmd(ucmd_T *cmd)
   NLUA_CLEAR_REF(cmd->uc_luaref);
 }
 
-/*
- * Clear all user commands for "gap".
- */
+/// Clear all user commands for "gap".
 void uc_clear(garray_T *gap)
 {
   GA_DEEP_CLEAR(gap, ucmd_T, free_ucmd);
@@ -5831,6 +5776,7 @@ static void ex_delcommand(exarg_T *eap)
 /// @param[out]  start Start of the split
 /// @param[out]  end End of the split
 /// @param[in]  length Length of the string
+///
 /// @return  false if it's the last split (don't call again), true otherwise (call again).
 bool uc_split_args_iter(const char_u *arg, int iter, int *start, int *end, int length)
 {
@@ -5846,9 +5792,7 @@ bool uc_split_args_iter(const char_u *arg, int iter, int *start, int *end, int l
   return false;
 }
 
-/*
- * split and quote args for <f-args>
- */
+/// split and quote args for <f-args>
 static char_u *uc_split_args(char_u *arg, size_t *lenp)
 {
   char_u *buf;
@@ -6361,17 +6305,14 @@ static char_u *expand_user_command_name(int idx)
 {
   return get_user_commands(NULL, idx - CMD_SIZE);
 }
-/*
- * Function given to ExpandGeneric() to obtain the list of user address type names.
- */
+
+/// Function given to ExpandGeneric() to obtain the list of user address type names.
 char_u *get_user_cmd_addr_type(expand_T *xp, int idx)
 {
   return (char_u *)addr_type_complete[idx].name;
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of user command names.
- */
+/// Function given to ExpandGeneric() to obtain the list of user command names.
 char_u *get_user_commands(expand_T *xp FUNC_ATTR_UNUSED, int idx)
   FUNC_ATTR_PURE FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -6388,9 +6329,10 @@ char_u *get_user_commands(expand_T *xp FUNC_ATTR_UNUSED, int idx)
   return NULL;
 }
 
-// Get the name of user command "idx".  "cmdidx" can be CMD_USER or
-// CMD_USER_BUF.
-// Returns NULL if the command is not found.
+/// Get the name of user command "idx".  "cmdidx" can be CMD_USER or
+/// CMD_USER_BUF.
+///
+/// @return  NULL if the command is not found.
 static char_u *get_user_command_name(int idx, int cmdidx)
 {
   if (cmdidx == CMD_USER && idx < ucmds.ga_len) {
@@ -6407,10 +6349,8 @@ static char_u *get_user_command_name(int idx, int cmdidx)
   return NULL;
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of user command
- * attributes.
- */
+/// Function given to ExpandGeneric() to obtain the list of user command
+/// attributes.
 char_u *get_user_cmd_flags(expand_T *xp, int idx)
 {
   static char *user_cmd_flags[] = { "addr",   "bang",     "bar",
@@ -6423,9 +6363,7 @@ char_u *get_user_cmd_flags(expand_T *xp, int idx)
   return (char_u *)user_cmd_flags[idx];
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of values for -nargs.
- */
+/// Function given to ExpandGeneric() to obtain the list of values for -nargs.
 char_u *get_user_cmd_nargs(expand_T *xp, int idx)
 {
   static char *user_cmd_nargs[] = { "0", "1", "*", "?", "+" };
@@ -6436,9 +6374,7 @@ char_u *get_user_cmd_nargs(expand_T *xp, int idx)
   return (char_u *)user_cmd_nargs[idx];
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of values for -complete.
- */
+/// Function given to ExpandGeneric() to obtain the list of values for -complete.
 char_u *get_user_cmd_complete(expand_T *xp, int idx)
 {
   if (idx >= (int)ARRAY_SIZE(command_complete)) {
@@ -6452,9 +6388,7 @@ char_u *get_user_cmd_complete(expand_T *xp, int idx)
   }
 }
 
-/*
- * Parse address type argument
- */
+/// Parse address type argument
 int parse_addr_type_arg(char_u *value, int vallen, cmd_addr_T *addr_type_arg)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -6481,13 +6415,12 @@ int parse_addr_type_arg(char_u *value, int vallen, cmd_addr_T *addr_type_arg)
   return OK;
 }
 
-/*
- * Parse a completion argument "value[vallen]".
- * The detected completion goes in "*complp", argument type in "*argt".
- * When there is an argument, for function and user defined completion, it's
- * copied to allocated memory and stored in "*compl_arg".
- * Returns FAIL if something is wrong.
- */
+/// Parse a completion argument "value[vallen]".
+/// The detected completion goes in "*complp", argument type in "*argt".
+/// When there is an argument, for function and user defined completion, it's
+/// copied to allocated memory and stored in "*compl_arg".
+///
+/// @return  FAIL if something is wrong.
 int parse_compl_arg(const char_u *value, int vallen, int *complp, uint32_t *argt,
                     char_u **compl_arg)
   FUNC_ATTR_NONNULL_ALL
@@ -6592,10 +6525,8 @@ static void ex_highlight(exarg_T *eap)
 }
 
 
-/*
- * Call this function if we thought we were going to exit, but we won't
- * (because of an error).  May need to restore the terminal mode.
- */
+/// Call this function if we thought we were going to exit, but we won't
+/// (because of an error).  May need to restore the terminal mode.
 void not_exiting(void)
 {
   exiting = false;
@@ -6630,8 +6561,8 @@ bool before_quit_autocmds(win_T *wp, bool quit_all, bool forceit)
   return false;
 }
 
-// ":quit": quit current window, quit Vim if the last window is closed.
-// ":{nr}quit": quit window {nr}
+/// ":quit": quit current window, quit Vim if the last window is closed.
+/// ":{nr}quit": quit window {nr}
 static void ex_quit(exarg_T *eap)
 {
   if (cmdwin_type != 0) {
@@ -6731,9 +6662,7 @@ static void ex_quit_all(exarg_T *eap)
   not_exiting();
 }
 
-/*
- * ":close": close current window, unless it is the last one
- */
+/// ":close": close current window, unless it is the last one
 static void ex_close(exarg_T *eap)
 {
   win_T *win = NULL;
@@ -6759,9 +6688,7 @@ static void ex_close(exarg_T *eap)
   }
 }
 
-/*
- * ":pclose": Close any preview window.
- */
+/// ":pclose": Close any preview window.
 static void ex_pclose(exarg_T *eap)
 {
   FOR_ALL_WINDOWS_IN_TAB(win, curtab) {
@@ -6812,10 +6739,8 @@ void ex_win_close(int forceit, win_T *win, tabpage_T *tp)
   }
 }
 
-/*
- * ":tabclose": close current tab page, unless it is the last one.
- * ":tabclose N": close tab page N.
- */
+/// ":tabclose": close current tab page, unless it is the last one.
+/// ":tabclose N": close tab page N.
 static void ex_tabclose(exarg_T *eap)
 {
   tabpage_T *tp;
@@ -6876,9 +6801,7 @@ static void ex_tabonly(exarg_T *eap)
   }
 }
 
-/*
- * Close the current tab page.
- */
+/// Close the current tab page.
 void tabpage_close(int forceit)
 {
   // First close all the windows but the current one.  If that worked then
@@ -6894,12 +6817,10 @@ void tabpage_close(int forceit)
   }
 }
 
-/*
- * Close tab page "tp", which is not the current tab page.
- * Note that autocommands may make "tp" invalid.
- * Also takes care of the tab pages line disappearing when closing the
- * last-but-one tab page.
- */
+/// Close tab page "tp", which is not the current tab page.
+/// Note that autocommands may make "tp" invalid.
+/// Also takes care of the tab pages line disappearing when closing the
+/// last-but-one tab page.
 void tabpage_close_other(tabpage_T *tp, int forceit)
 {
   int done = 0;
@@ -6927,9 +6848,7 @@ void tabpage_close_other(tabpage_T *tp, int forceit)
   }
 }
 
-/*
- * ":only".
- */
+/// ":only".
 static void ex_only(exarg_T *eap)
 {
   win_T *wp;
@@ -6953,10 +6872,8 @@ static void ex_only(exarg_T *eap)
   close_others(TRUE, eap->forceit);
 }
 
-/*
- * ":all" and ":sall".
- * Also used for ":tab drop file ..." after setting the argument list.
- */
+/// ":all" and ":sall".
+/// Also used for ":tab drop file ..." after setting the argument list.
 void ex_all(exarg_T *eap)
 {
   if (eap->addr_count == 0) {
@@ -7011,7 +6928,7 @@ static void ex_stop(exarg_T *eap)
   apply_autocmds(EVENT_VIMRESUME, NULL, NULL, false, NULL);
 }
 
-// ":exit", ":xit" and ":wq": Write file and quit the current window.
+/// ":exit", ":xit" and ":wq": Write file and quit the current window.
 static void ex_exit(exarg_T *eap)
 {
   if (cmdwin_type != 0) {
@@ -7047,9 +6964,7 @@ static void ex_exit(exarg_T *eap)
   }
 }
 
-/*
- * ":print", ":list", ":number".
- */
+/// ":print", ":list", ":number".
 static void ex_print(exarg_T *eap)
 {
   if (curbuf->b_ml.ml_flags & ML_EMPTY) {
@@ -7079,29 +6994,23 @@ static void ex_goto(exarg_T *eap)
   goto_byte(eap->line2);
 }
 
-/*
- * Clear an argument list: free all file names and reset it to zero entries.
- */
+/// Clear an argument list: free all file names and reset it to zero entries.
 void alist_clear(alist_T *al)
 {
 #define FREE_AENTRY_FNAME(arg) xfree(arg->ae_fname)
   GA_DEEP_CLEAR(&al->al_ga, aentry_T, FREE_AENTRY_FNAME);
 }
 
-/*
- * Init an argument list.
- */
+/// Init an argument list.
 void alist_init(alist_T *al)
 {
   ga_init(&al->al_ga, (int)sizeof(aentry_T), 5);
 }
 
 
-/*
- * Remove a reference from an argument list.
- * Ignored when the argument list is the global one.
- * If the argument list is no longer used by any window, free it.
- */
+/// Remove a reference from an argument list.
+/// Ignored when the argument list is the global one.
+/// If the argument list is no longer used by any window, free it.
 void alist_unlink(alist_T *al)
 {
   if (al != &global_alist && --al->al_refcount <= 0) {
@@ -7110,9 +7019,7 @@ void alist_unlink(alist_T *al)
   }
 }
 
-/*
- * Create a new argument list and use it for the current window.
- */
+/// Create a new argument list and use it for the current window.
 void alist_new(void)
 {
   curwin->w_alist = xmalloc(sizeof(*curwin->w_alist));
@@ -7122,11 +7029,10 @@ void alist_new(void)
 }
 
 #if !defined(UNIX)
-/*
- * Expand the file names in the global argument list.
- * If "fnum_list" is not NULL, use "fnum_list[fnum_len]" as a list of buffer
- * numbers to be re-used.
- */
+
+/// Expand the file names in the global argument list.
+/// If "fnum_list" is not NULL, use "fnum_list[fnum_len]" as a list of buffer
+/// numbers to be re-used.
 void alist_expand(int *fnum_list, int fnum_len)
 {
   char_u **old_arg_files;
@@ -7157,10 +7063,8 @@ void alist_expand(int *fnum_list, int fnum_len)
 }
 #endif
 
-/*
- * Set the argument list for the current window.
- * Takes over the allocated files[] and the allocated fnames in it.
- */
+/// Set the argument list for the current window.
+/// Takes over the allocated files[] and the allocated fnames in it.
 void alist_set(alist_T *al, int count, char_u **files, int use_curbuf, int *fnum_list, int fnum_len)
 {
   int i;
@@ -7224,9 +7128,8 @@ void alist_add(alist_T *al, char_u *fname, int set_fnum)
 }
 
 #if defined(BACKSLASH_IN_FILENAME)
-/*
- * Adjust slashes in file names.  Called after 'shellslash' was set.
- */
+
+/// Adjust slashes in file names.  Called after 'shellslash' was set.
 void alist_slash_adjust(void)
 {
   for (int i = 0; i < GARGCOUNT; ++i) {
@@ -7272,27 +7175,23 @@ static void ex_recover(exarg_T *eap)
   recoverymode = false;
 }
 
-/*
- * Command modifier used in a wrong way.
- */
+/// Command modifier used in a wrong way.
 static void ex_wrongmodifier(exarg_T *eap)
 {
   eap->errmsg = e_invcmd;
 }
 
-/*
- * :sview [+command] file       split window with new file, read-only
- * :split [[+command] file]     split window with current or new file
- * :vsplit [[+command] file]    split window vertically with current or new file
- * :new [[+command] file]       split window with no or new file
- * :vnew [[+command] file]      split vertically window with no or new file
- * :sfind [+command] file       split window with file in 'path'
- *
- * :tabedit                     open new Tab page with empty window
- * :tabedit [+command] file     open new Tab page and edit "file"
- * :tabnew [[+command] file]    just like :tabedit
- * :tabfind [+command] file     open new Tab page and find "file"
- */
+/// :sview [+command] file       split window with new file, read-only
+/// :split [[+command] file]     split window with current or new file
+/// :vsplit [[+command] file]    split window vertically with current or new file
+/// :new [[+command] file]       split window with no or new file
+/// :vnew [[+command] file]      split vertically window with no or new file
+/// :sfind [+command] file       split window with file in 'path'
+///
+/// :tabedit                     open new Tab page with empty window
+/// :tabedit [+command] file     open new Tab page and edit "file"
+/// :tabnew [[+command] file]    just like :tabedit
+/// :tabfind [+command] file     open new Tab page and find "file"
 void ex_splitview(exarg_T *eap)
 {
   win_T *old_curwin = curwin;
@@ -7355,9 +7254,7 @@ theend:
   xfree(fname);
 }
 
-/*
- * Open a new tab page.
- */
+/// Open a new tab page.
 void tabpage_new(void)
 {
   exarg_T ea;
@@ -7369,9 +7266,7 @@ void tabpage_new(void)
   ex_splitview(&ea);
 }
 
-/*
- * :tabnext command
- */
+/// :tabnext command
 static void ex_tabnext(exarg_T *eap)
 {
   int tab_number;
@@ -7418,9 +7313,7 @@ static void ex_tabnext(exarg_T *eap)
   }
 }
 
-/*
- * :tabmove command
- */
+/// :tabmove command
 static void ex_tabmove(exarg_T *eap)
 {
   int tab_number = get_tabpage_arg(eap);
@@ -7429,9 +7322,7 @@ static void ex_tabmove(exarg_T *eap)
   }
 }
 
-/*
- * :tabs command: List tabs and their contents.
- */
+/// :tabs command: List tabs and their contents.
 static void ex_tabs(exarg_T *eap)
 {
   int tabcount = 1;
@@ -7477,10 +7368,8 @@ static void ex_tabs(exarg_T *eap)
 }
 
 
-/*
- * ":mode":
- * If no argument given, get the screen size and redraw.
- */
+/// ":mode":
+/// If no argument given, get the screen size and redraw.
 static void ex_mode(exarg_T *eap)
 {
   if (*eap->arg == NUL) {
@@ -7491,10 +7380,8 @@ static void ex_mode(exarg_T *eap)
   }
 }
 
-/*
- * ":resize".
- * set, increment or decrement current window height
- */
+/// ":resize".
+/// set, increment or decrement current window height
 static void ex_resize(exarg_T *eap)
 {
   int n;
@@ -7524,9 +7411,7 @@ static void ex_resize(exarg_T *eap)
   }
 }
 
-/*
- * ":find [+command] <file>" command.
- */
+/// ":find [+command] <file>" command.
 static void ex_find(exarg_T *eap)
 {
   char_u *fname;
@@ -7703,11 +7588,9 @@ static void ex_swapname(exarg_T *eap)
   }
 }
 
-/*
- * ":syncbind" forces all 'scrollbind' windows to have the same relative
- * offset.
- * (1998-11-02 16:21:01  R. Edward Ralston <eralston@computer.org>)
- */
+/// ":syncbind" forces all 'scrollbind' windows to have the same relative
+/// offset.
+/// (1998-11-02 16:21:01  R. Edward Ralston <eralston@computer.org>)
 static void ex_syncbind(exarg_T *eap)
 {
   win_T *save_curwin = curwin;
@@ -7838,7 +7721,7 @@ void free_cd_dir(void)
 
 #endif
 
-// Get the previous directory for the given chdir scope.
+/// Get the previous directory for the given chdir scope.
 static char_u *get_prevdir(CdScope scope)
 {
   switch (scope) {
@@ -8003,9 +7886,7 @@ void ex_cd(exarg_T *eap)
   }
 }
 
-/*
- * ":pwd".
- */
+/// ":pwd".
 static void ex_pwd(exarg_T *eap)
 {
   if (os_dirname(NameBuff, MAXPATHL) == OK) {
@@ -8030,9 +7911,7 @@ static void ex_pwd(exarg_T *eap)
   }
 }
 
-/*
- * ":=".
- */
+/// ":=".
 static void ex_equal(exarg_T *eap)
 {
   smsg("%" PRId64, (int64_t)eap->line2);
@@ -8063,9 +7942,7 @@ static void ex_sleep(exarg_T *eap)
   do_sleep(len);
 }
 
-/*
- * Sleep for "msec" milliseconds, but keep checking for a CTRL-C every second.
- */
+/// Sleep for "msec" milliseconds, but keep checking for a CTRL-C every second.
 void do_sleep(long