Merge pull request #17739 from dundargoc/doxygen/ex_cmds

refactor(ex_cmds): convert function comments to doxygen format

src/nvim/ex_cmds.c

@@ -225,9 +225,7 @@ void do_ascii(const exarg_T *const eap)
   msg((char *)IObuff);
 }
 
-/*
+/// ":left", ":center" and ":right": align text.
- * ":left", ":center" and ":right": align text.
- */
 void ex_align(exarg_T *eap)
 {
   pos_T save_curpos;
@@ -324,9 +322,7 @@ void ex_align(exarg_T *eap)
   beginline(BL_WHITE | BL_FIX);
 }
 
-/*
+/// @return  the length of the current line, excluding trailing white space.
- * Get the length of the current line, excluding trailing white space.
- */
 static int linelen(int *has_tab)
 {
   char_u *line;
@@ -452,7 +448,7 @@ static int sort_compare(const void *s1, const void *s2)
   return result;
 }
 
-// ":sort".
+/// ":sort".
 void ex_sort(exarg_T *eap)
 {
   regmatch_T regmatch;
@@ -723,9 +719,7 @@ sortend:
   }
 }
 
-/*
+/// ":retab".
- * ":retab".
- */
 void ex_retab(exarg_T *eap)
 {
   linenr_T lnum;
@@ -907,11 +901,9 @@ void ex_retab(exarg_T *eap)
   u_clearline();
 }
 
-/*
+/// :move command - move lines line1-line2 to line dest
- * :move command - move lines line1-line2 to line dest
+///
- *
+/// @return  FAIL for failure, OK otherwise
- * return FAIL for failure, OK otherwise
- */
 int do_move(linenr_T line1, linenr_T line2, linenr_T dest)
 {
   char_u *str;
@@ -1062,9 +1054,7 @@ int do_move(linenr_T line1, linenr_T line2, linenr_T dest)
   return OK;
 }
 
-/*
+/// ":copy"
- * ":copy"
- */
 void ex_copy(linenr_T line1, linenr_T line2, linenr_T n)
 {
   linenr_T count;
@@ -1132,11 +1122,9 @@ void free_prev_shellcmd(void)
 
 #endif
 
-/*
+/// Handle the ":!cmd" command.  Also for ":r !cmd" and ":w !cmd"
- * Handle the ":!cmd" command.  Also for ":r !cmd" and ":w !cmd"
+/// Bangs in the argument are replaced with the previously entered command.
- * Bangs in the argument are replaced with the previously entered command.
+/// Remember the argument.
- * Remember the argument.
- */
 void do_bang(int addr_count, exarg_T *eap, bool forceit, bool do_in, bool do_out)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -1684,9 +1672,7 @@ void print_line_no_prefix(linenr_T lnum, int use_number, int list)
   msg_prt_line(ml_get(lnum), list);
 }
 
-/*
+/// Print a text line.  Also in silent mode ("ex -s").
- * Print a text line.  Also in silent mode ("ex -s").
- */
 void print_line(linenr_T lnum, int use_number, int list)
 {
   int save_silent = silent_mode;
@@ -1754,9 +1740,7 @@ int rename_buffer(char_u *new_fname)
   return OK;
 }
 
-/*
+/// ":file[!] [fname]".
- * ":file[!] [fname]".
- */
 void ex_file(exarg_T *eap)
 {
   // ":0file" removes the file name.  Check for illegal uses ":3file",
@@ -1782,9 +1766,7 @@ void ex_file(exarg_T *eap)
   }
 }
 
-/*
+/// ":update".
- * ":update".
- */
 void ex_update(exarg_T *eap)
 {
   if (curbufIsChanged()) {
@@ -1792,9 +1774,7 @@ void ex_update(exarg_T *eap)
   }
 }
 
-/*
+/// ":write" and ":saveas".
- * ":write" and ":saveas".
- */
 void ex_write(exarg_T *eap)
 {
   if (eap->cmdidx == CMD_saveas) {
@@ -1810,14 +1790,12 @@ void ex_write(exarg_T *eap)
   }
 }
 
-/*
+/// write current buffer to file 'eap->arg'
- * write current buffer to file 'eap->arg'
+/// if 'eap->append' is TRUE, append to the file
- * if 'eap->append' is TRUE, append to the file
+///
- *
+/// if *eap->arg == NUL write to current file
- * if *eap->arg == NUL write to current file
+///
- *
+/// @return  FAIL for failure, OK otherwise
- * return FAIL for failure, OK otherwise
- */
 int do_write(exarg_T *eap)
 {
   int other;
@@ -2070,9 +2048,7 @@ int check_overwrite(exarg_T *eap, buf_T *buf, char_u *fname, char_u *ffname, int
   return OK;
 }
 
-/*
+/// Handle ":wnext", ":wNext" and ":wprevious" commands.
- * Handle ":wnext", ":wNext" and ":wprevious" commands.
- */
 void ex_wnext(exarg_T *eap)
 {
   int i;
@@ -2089,9 +2065,7 @@ void ex_wnext(exarg_T *eap)
   }
 }
 
-/*
+/// ":wall", ":wqall" and ":xall": Write all changed files (and exit).
- * ":wall", ":wqall" and ":xall": Write all changed files (and exit).
- */
 void do_wqall(exarg_T *eap)
 {
   int error = 0;
@@ -2149,8 +2123,9 @@ void do_wqall(exarg_T *eap)
   }
 }
 
-// Check the 'write' option.
+/// Check the 'write' option.
-// Return true and give a message when it's not st.
+///
+/// @return  true and give a message when it's not st.
 bool not_writing(void)
 {
   if (p_write) {
@@ -2160,11 +2135,9 @@ bool not_writing(void)
   return true;
 }
 
-/*
+/// Check if a buffer is read-only (either 'readonly' option is set or file is
- * Check if a buffer is read-only (either 'readonly' option is set or file is
+/// read-only). Ask for overruling in a dialog. Return TRUE and give an error
- * read-only). Ask for overruling in a dialog. Return TRUE and give an error
+/// message when the buffer is readonly.
- * message when the buffer is readonly.
- */
 static int check_readonly(int *forceit, buf_T *buf)
 {
   // Handle a file being readonly when the 'readonly' option is set or when
@@ -2205,15 +2178,16 @@ static int check_readonly(int *forceit, buf_T *buf)
   return FALSE;
 }
 
-// Try to abandon the current file and edit a new or existing file.
+/// Try to abandon the current file and edit a new or existing file.
-// "fnum" is the number of the file, if zero use "ffname_arg"/"sfname_arg".
+///
-// "lnum" is the line number for the cursor in the new file (if non-zero).
+/// @param fnum  the number of the file, if zero use "ffname_arg"/"sfname_arg".
-//
+/// @param lnum  the line number for the cursor in the new file (if non-zero).
-// Return:
+///
-// GETFILE_ERROR for "normal" error,
+/// @return:
-// GETFILE_NOT_WRITTEN for "not written" error,
+///           GETFILE_ERROR for "normal" error,
-// GETFILE_SAME_FILE for success
+///           GETFILE_NOT_WRITTEN for "not written" error,
-// GETFILE_OPEN_OTHER for successfully opening another file.
+///           GETFILE_SAME_FILE for success
+///           GETFILE_OPEN_OTHER for successfully opening another file.
 int getfile(int fnum, char_u *ffname_arg, char_u *sfname_arg, int setpm, linenr_T lnum, int forceit)
 {
   char_u *ffname = ffname_arg;
@@ -2934,9 +2908,7 @@ static void delbuf_msg(char_u *name)
 
 static int append_indent = 0;       // autoindent for first line
 
-/*
+/// ":insert" and ":append", also used by ":change"
- * ":insert" and ":append", also used by ":change"
- */
 void ex_append(exarg_T *eap)
 {
   char_u *theline;
@@ -3078,9 +3050,7 @@ void ex_append(exarg_T *eap)
   ex_no_reprint = true;
 }
 
-/*
+/// ":change"
- * ":change"
- */
 void ex_change(exarg_T *eap)
 {
   linenr_T lnum;
@@ -3247,9 +3217,9 @@ void ex_z(exarg_T *eap)
   ex_no_reprint = true;
 }
 
-// Check if the secure flag is set (.exrc or .vimrc in current directory).
+/// @return  true if the secure flag is set (.exrc or .vimrc in current directory)
-// If so, give an error message and return true.
+///          and also give an error message.
-// Otherwise, return false.
+///          Otherwise, return false.
 bool check_secure(void)
 {
   if (secure) {
@@ -4533,22 +4503,20 @@ static void global_exe_one(char_u *const cmd, const linenr_T lnum)
   }
 }
 
-/*
+/// Execute a global command of the form:
- * Execute a global command of the form:
+///
- *
+/// g/pattern/X : execute X on all lines where pattern matches
- * g/pattern/X : execute X on all lines where pattern matches
+/// v/pattern/X : execute X on all lines where pattern does not match
- * v/pattern/X : execute X on all lines where pattern does not match
+///
- *
+/// where 'X' is an EX command
- * where 'X' is an EX command
+///
- *
+/// The command character (as well as the trailing slash) is optional, and
- * The command character (as well as the trailing slash) is optional, and
+/// is assumed to be 'p' if missing.
- * is assumed to be 'p' if missing.
+///
- *
+/// This is implemented in two passes: first we scan the file for the pattern and
- * This is implemented in two passes: first we scan the file for the pattern and
+/// set a mark for each line that (not) matches. Secondly we execute the command
- * set a mark for each line that (not) matches. Secondly we execute the command
+/// for each line that has a mark. This is required because after deleting
- * for each line that has a mark. This is required because after deleting
+/// lines we do not know where to search for the next match.
- * lines we do not know where to search for the next match.
- */
 void ex_global(exarg_T *eap)
 {
   linenr_T lnum;                // line number according to old situation
@@ -4764,9 +4732,7 @@ bool prepare_tagpreview(bool undo_sync)
 }
 
 
-/*
+/// ":help": open a read-only window on a help file
- * ":help": open a read-only window on a help file
- */
 void ex_help(exarg_T *eap)
 {
   char_u *arg;
@@ -4949,11 +4915,10 @@ erret:
 }
 
 
-/*
+/// In an argument search for a language specifiers in the form "@xx".
- * In an argument search for a language specifiers in the form "@xx".
+/// Changes the "@" to NUL if found, and returns a pointer to "xx".
- * Changes the "@" to NUL if found, and returns a pointer to "xx".
+///
- * Returns NULL if not found.
+/// @return  NULL if not found.
- */
 char_u *check_help_lang(char_u *arg)
 {
   int len = (int)STRLEN(arg);
@@ -5019,10 +4984,8 @@ int help_heuristic(char_u *matched_string, int offset, int wrong_case)
   return (int)(100 * num_letters + STRLEN(matched_string) + offset);
 }
 
-/*
+/// Compare functions for qsort() below, that checks the help heuristics number
- * Compare functions for qsort() below, that checks the help heuristics number
+/// that has been put after the tagname by find_tags().
- * that has been put after the tagname by find_tags().
- */
 static int help_compare(const void *s1, const void *s2)
 {
   char *p1;
@@ -5033,10 +4996,10 @@ static int help_compare(const void *s1, const void *s2)
   return strcmp(p1, p2);
 }
 
-// Find all help tags matching "arg", sort them and return in matches[], with
+/// Find all help tags matching "arg", sort them and return in matches[], with
-// the number of matches in num_matches.
+/// the number of matches in num_matches.
-// The matches will be sorted with a "best" match algorithm.
+/// The matches will be sorted with a "best" match algorithm.
-// When "keep_lang" is true try keeping the language of the current buffer.
+/// When "keep_lang" is true try keeping the language of the current buffer.
 int find_help_tags(const char_u *arg, int *num_matches, char_u ***matches, bool keep_lang)
 {
   int i;
@@ -5308,10 +5271,8 @@ static void prepare_help_buffer(void)
   set_buflisted(FALSE);
 }
 
-/*
+/// After reading a help file: May cleanup a help buffer when syntax
- * After reading a help file: May cleanup a help buffer when syntax
+/// highlighting is not used.
- * highlighting is not used.
- */
 void fix_help_buffer(void)
 {
   linenr_T lnum;
@@ -5507,17 +5468,13 @@ void fix_help_buffer(void)
   }
 }
 
-/*
+/// ":exusage"
- * ":exusage"
- */
 void ex_exusage(exarg_T *eap)
 {
   do_cmdline_cmd("help ex-cmd-index");
 }
 
-/*
+/// ":viusage"
- * ":viusage"
- */
 void ex_viusage(exarg_T *eap)
 {
   do_cmdline_cmd("help normal-index");
@@ -5826,9 +5783,7 @@ static void helptags_cb(char_u *fname, void *cookie)
   do_helptags(fname, *(bool *)cookie, true);
 }
 
-/*
+/// ":helptags"
- * ":helptags"
- */
 void ex_helptags(exarg_T *eap)
 {
   expand_T xpc;
@@ -5857,9 +5812,7 @@ void ex_helptags(exarg_T *eap)
   }
 }
 
-/*
+/// ":helpclose": Close one help window
- * ":helpclose": Close one help window
- */
 void ex_helpclose(exarg_T *eap)
 {
   FOR_ALL_WINDOWS_IN_TAB(win, curtab) {
@@ -5873,7 +5826,7 @@ void ex_helpclose(exarg_T *eap)
 /// Tries to enter to an existing window of given buffer. If no existing buffer
 /// is found, creates a new split.
 ///
-/// Returns OK/FAIL.
+/// @return  OK/FAIL.
 int sub_preview_win(buf_T *preview_buf)
 {
   if (preview_buf != NULL) {
@@ -6115,9 +6068,11 @@ void ex_substitute(exarg_T *eap)
 
 /// Skip over the pattern argument of ":vimgrep /pat/[g][j]".
 /// Put the start of the pattern in "*s", unless "s" is NULL.
-/// If "flags" is not NULL put the flags in it: VGR_GLOBAL, VGR_NOJUMP.
+///
-/// If "s" is not NULL terminate the pattern with a NUL.
+/// @param flags  if not NULL, put the flags in it: VGR_GLOBAL, VGR_NOJUMP.
-/// Return a pointer to the char just past the pattern plus flags.
+/// @param s      if not NULL, terminate the pattern with a NUL.
+///
+/// @return  a pointer to the char just past the pattern plus flags.
 char_u *skip_vimgrep_pat(char_u *p, char_u **s, int *flags)
 {
   int c;

src/nvim/ex_cmds2.c

@@ -436,8 +436,8 @@ static void script_dump_profile(FILE *fd)
   }
 }
 
-/// Return true when a function defined in the current script should be
+/// @return  true when a function defined in the current script should be
-/// profiled.
+///          profiled.
 bool prof_def_func(void)
 {
   if (current_sctx.sc_sid > 0) {
@@ -492,7 +492,7 @@ void autowrite_all(void)
   }
 }
 
-/// Return true if buffer was changed and cannot be abandoned.
+/// @return  true if buffer was changed and cannot be abandoned.
 /// For flags use the CCGD_ values.
 bool check_changed(buf_T *buf, int flags)
 {
@@ -616,7 +616,7 @@ bool dialog_close_terminal(buf_T *buf)
   return ret == VIM_YES;
 }
 
-/// Return true if the buffer "buf" can be abandoned, either by making it
+/// @return true if the buffer "buf" can be abandoned, either by making it
 /// hidden, autowriting it or unloading it.
 bool can_abandon(buf_T *buf, int forceit)
 {
@@ -771,8 +771,8 @@ theend:
   return ret;
 }
 
-/// Return FAIL if there is no file name, OK if there is one.
+/// @return  FAIL if there is no file name, OK if there is one.
-/// Give error message for FAIL.
+///          Give error message for FAIL.
 int check_fname(void)
 {
   if (curbuf->b_ffname == NULL) {
@@ -784,7 +784,7 @@ int check_fname(void)
 
 /// Flush the contents of a buffer, unless it has no file name.
 ///
-/// @return FAIL for failure, OK otherwise
+/// @return  FAIL for failure, OK otherwise
 int buf_write_all(buf_T *buf, int forceit)
 {
   int retval;
@@ -808,7 +808,8 @@ int buf_write_all(buf_T *buf, int forceit)
 
 /// Isolate one argument, taking backticks.
 /// Changes the argument in-place, puts a NUL after it.  Backticks remain.
-/// Return a pointer to the start of the next argument.
+///
+/// @return  a pointer to the start of the next argument.
 static char_u *do_one_arg(char_u *str)
 {
   char_u *p;
@@ -859,7 +860,7 @@ static void get_arglist(garray_T *gap, char_u *str, int escaped)
 /// Parse a list of arguments (file names), expand them and return in
 /// "fnames[fcountp]".  When "wig" is true, removes files matching 'wildignore'.
 ///
-/// @return FAIL or OK.
+/// @return  FAIL or OK.
 int get_arglist_exp(char_u *str, int *fcountp, char_u ***fnamesp, bool wig)
 {
   garray_T ga;
@@ -889,7 +890,7 @@ int get_arglist_exp(char_u *str, int *fcountp, char_u ***fnamesp, bool wig)
 ///         0 means before first one
 /// @param will_edit  will edit added argument
 ///
-/// @return FAIL for failure, OK otherwise.
+/// @return  FAIL for failure, OK otherwise.
 static int do_arglist(char_u *str, int what, int after, bool will_edit)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -988,8 +989,8 @@ static void alist_check_arg_idx(void)
   }
 }
 
-/// Return true if window "win" is editing the file at the current argument
+/// @return  true if window "win" is editing the file at the current argument
-/// index.
+///          index.
 static bool editing_arg_idx(win_T *win)
 {
   return !(win->w_arg_idx >= WARGCOUNT(win)
@@ -1717,13 +1718,13 @@ linenr_T *source_breakpoint(void *cookie)
   return &((struct source_cookie *)cookie)->breakpoint;
 }
 
-/// Return the address holding the debug tick for a source cookie.
+/// @return  the address holding the debug tick for a source cookie.
 int *source_dbg_tick(void *cookie)
 {
   return &((struct source_cookie *)cookie)->dbg_tick;
 }
 
-/// Return the nesting level for a source cookie.
+/// @return  the nesting level for a source cookie.
 int source_level(void *cookie)
 {
   return ((struct source_cookie *)cookie)->level;
@@ -1788,7 +1789,8 @@ static char_u *get_str_line(int c, void *cookie, int indent, bool do_concat)
 ///
 /// @param  name  File name of the script. NULL for anonymous :source.
 /// @param[out]  sid_out  SID of the new item.
-/// @return pointer to the created script item.
+///
+/// @return  pointer to the created script item.
 scriptitem_T *new_script_item(char_u *const name, scid_T *const sid_out)
 {
   static scid_T last_current_SID = 0;
@@ -1896,7 +1898,7 @@ int do_source_str(const char *cmd, const char *traceback_name)
 /// @param check_other  check for .vimrc and _vimrc
 /// @param is_vimrc     DOSO_ value
 ///
-/// @return FAIL if file could not be opened, OK otherwise
+/// @return  FAIL if file could not be opened, OK otherwise
 int do_source(char *fname, int check_other, int is_vimrc)
 {
   struct source_cookie cookie;
@@ -2145,6 +2147,7 @@ theend:
 
 /// Check if fname was sourced before to finds its SID.
 /// If it's new, generate a new SID.
+///
 /// @param[in] fname file path of script
 /// @param[out] ret_sctx sctx of this script
 scriptitem_T *get_current_script_id(char_u *fname, sctx_T *ret_sctx)
@@ -2614,9 +2617,9 @@ void do_finish(exarg_T *eap, int reanimate)
 }
 
 
-/// Return true when a sourced file had the ":finish" command: Don't give error
+/// @return  true when a sourced file had the ":finish" command: Don't give error
-/// message for missing ":endif".
+///          message for missing ":endif".
-/// Return false when not sourcing a file.
+///          false when not sourcing a file.
 bool source_finished(LineGetter fgetline, void *cookie)
 {
   return getline_equal(fgetline, cookie, getsourceline)
@@ -2653,8 +2656,8 @@ static char *get_locale_val(int what)
 }
 #endif
 
-// Return true when "lang" starts with a valid language name.
+/// @return  true when "lang" starts with a valid language name.
-// Rejects NULL, empty string, "C", "C.UTF-8" and others.
+///          Rejects NULL, empty string, "C", "C.UTF-8" and others.
 static bool is_valid_mess_lang(char *lang)
 {
   return lang != NULL && ASCII_ISALPHA(lang[0]) && ASCII_ISALPHA(lang[1]);
@@ -2757,11 +2760,10 @@ void set_lang_var(void)
 }
 
 #ifdef HAVE_WORKING_LIBINTL
-///
+
 /// ":language":  Set the language (locale).
 ///
 /// @param eap
-///
 void ex_language(exarg_T *eap)
 {
   char *loc;
@@ -2870,8 +2872,9 @@ static char_u **locales = NULL;       // Array of all available locales
 # ifndef WIN32
 static bool did_init_locales = false;
 
-/// Return an array of strings for all available locales + NULL for the
+/// @return  an array of strings for all available locales + NULL for the
-/// last element.  Return NULL in case of error.
+///          last element or,
+///          NULL in case of error.
 static char_u **find_locales(void)
 {
   garray_T locales_ga;