Merge pull request #17739 from dundargoc/doxygen/ex_cmds

refactor(ex_cmds): convert function comments to doxygen format
This commit is contained in:
bfredl 2022-03-16 20:52:40 +01:00 committed by GitHub
commit aeae88f32a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 109 additions and 151 deletions

View File

@ -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);
}
/*
* Get the length of the current line, excluding trailing white space.
*/
/// @return 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
*
* return FAIL for failure, OK otherwise
*/
/// :move command - move lines line1-line2 to line dest
///
/// @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"
* Bangs in the argument are replaced with the previously entered command.
* Remember the argument.
*/
/// Handle the ":!cmd" command. Also for ":r !cmd" and ":w !cmd"
/// Bangs in the argument are replaced with the previously entered command.
/// 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'
* if 'eap->append' is TRUE, append to the file
*
* if *eap->arg == NUL write to current file
*
* return FAIL for failure, OK otherwise
*/
/// write current buffer to file 'eap->arg'
/// if 'eap->append' is TRUE, append to the file
///
/// if *eap->arg == NUL write to current file
///
/// @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.
// Return true and give a message when it's not st.
/// Check the 'write' option.
///
/// @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
* read-only). Ask for overruling in a dialog. Return TRUE and give an error
* message when the buffer is readonly.
*/
/// 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
/// 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.
// "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).
//
// Return:
// GETFILE_ERROR for "normal" error,
// GETFILE_NOT_WRITTEN for "not written" error,
// GETFILE_SAME_FILE for success
// GETFILE_OPEN_OTHER for successfully opening another file.
/// Try to abandon the current file and edit a new or existing file.
///
/// @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,
/// GETFILE_NOT_WRITTEN for "not written" error,
/// 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).
// If so, give an error message and return true.
// Otherwise, return false.
/// @return true if the secure flag is set (.exrc or .vimrc in current directory)
/// and also give an error message.
/// 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:
*
* g/pattern/X : execute X on all lines where pattern matches
* v/pattern/X : execute X on all lines where pattern does not match
*
* where 'X' is an EX command
*
* The command character (as well as the trailing slash) is optional, and
* is assumed to be 'p' if missing.
*
* 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
* 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.
*/
/// Execute a global command of the form:
///
/// g/pattern/X : execute X on all lines where pattern matches
/// v/pattern/X : execute X on all lines where pattern does not match
///
/// where 'X' is an EX command
///
/// The command character (as well as the trailing slash) is optional, and
/// is assumed to be 'p' if missing.
///
/// 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
/// 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.
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".
* Changes the "@" to NUL if found, and returns a pointer to "xx".
* Returns NULL if not found.
*/
/// In an argument search for a language specifiers in the form "@xx".
/// Changes the "@" to NUL if found, and returns a pointer to "xx".
///
/// @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
* that has been put after the tagname by find_tags().
*/
/// Compare functions for qsort() below, that checks the help heuristics number
/// 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
// the number of matches in num_matches.
// The matches will be sorted with a "best" match algorithm.
// When "keep_lang" is true try keeping the language of the current buffer.
/// Find all help tags matching "arg", sort them and return in matches[], with
/// the number of matches in num_matches.
/// The matches will be sorted with a "best" match algorithm.
/// 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
* highlighting is not used.
*/
/// After reading a help file: May cleanup a help buffer when syntax
/// 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.
/// Return a pointer to the char just past the pattern plus flags.
///
/// @param flags if not NULL, put the flags in it: VGR_GLOBAL, VGR_NOJUMP.
/// @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;

View File

@ -436,8 +436,8 @@ static void script_dump_profile(FILE *fd)
}
}
/// Return true when a function defined in the current script should be
/// profiled.
/// @return true when a function defined in the current script should be
/// 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.
/// Give error message for FAIL.
/// @return FAIL if there is no file name, OK if there is one.
/// 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
/// index.
/// @return true if window "win" is editing the file at the current argument
/// 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
/// message for missing ":endif".
/// Return false when not sourcing a file.
/// @return true when a sourced file had the ":finish" command: Don't give error
/// message for missing ":endif".
/// 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.
// Rejects NULL, empty string, "C", "C.UTF-8" and others.
/// @return true when "lang" starts with a valid language name.
/// 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
/// last element. Return NULL in case of error.
/// @return an array of strings for all available locales + NULL for the
/// last element or,
/// NULL in case of error.
static char_u **find_locales(void)
{
garray_T locales_ga;