refactor(eval): convert function comments to doxygen format

1 files changed, 378 insertions, 470 deletions

diff --git a/src/nvim/eval.c b/src/nvim/eval.c
index 18b9039d60..464e408efa 100644
--- a/src/nvim/eval.c
+++ b/src/nvim/eval.c
@@ -331,7 +331,7 @@ void restore_v_event(dict_T *v_event, save_v_event_T *sve)
   }
 }
 
-// Return "n1" divided by "n2", taking care of dividing by zero.
+/// @return  "n1" divided by "n2", taking care of dividing by zero.
 varnumber_T num_divide(varnumber_T n1, varnumber_T n2)
   FUNC_ATTR_CONST FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -352,7 +352,7 @@ varnumber_T num_divide(varnumber_T n1, varnumber_T n2)
   return result;
 }
 
-// Return "n1" modulus "n2", taking care of dividing by zero.
+/// @return  "n1" modulus "n2", taking care of dividing by zero.
 varnumber_T num_modulus(varnumber_T n1, varnumber_T n2)
   FUNC_ATTR_CONST FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -360,9 +360,7 @@ varnumber_T num_modulus(varnumber_T n1, varnumber_T n2)
   return (n2 == 0) ? 0 : (n1 % n2);
 }
 
-/*
- * Initialize the global and v: variables.
- */
+/// Initialize the global and v: variables.
 void eval_init(void)
 {
   vimvars[VV_VERSION].vv_nr = VIM_VERSION_100;
@@ -502,10 +500,8 @@ void eval_clear(void)
 
 #endif
 
-/*
- * Set an internal variable to a string value. Creates the variable if it does
- * not already exist.
- */
+/// Set an internal variable to a string value. Creates the variable if it does
+/// not already exist.
 void set_internal_string_var(const char *name, char_u *value)
   FUNC_ATTR_NONNULL_ARG(1)
 {
@@ -523,9 +519,10 @@ static char_u *redir_endp = NULL;
 static char_u *redir_varname = NULL;
 
 /// Start recording command output to a variable
-/// Returns OK if successfully completed the setup.  FAIL otherwise.
 ///
 /// @param append  append to an existing variable
+///
+/// @return  OK if successfully completed the setup.  FAIL otherwise.
 int var_redir_start(char_u *name, int append)
 {
   int save_emsg;
@@ -586,15 +583,13 @@ int var_redir_start(char_u *name, int append)
   return OK;
 }
 
-/*
- * Append "value[value_len]" to the variable set by var_redir_start().
- * The actual appending is postponed until redirection ends, because the value
- * appended may in fact be the string we write to, changing it may cause freed
- * memory to be used:
- *   :redir => foo
- *   :let foo
- *   :redir END
- */
+/// Append "value[value_len]" to the variable set by var_redir_start().
+/// The actual appending is postponed until redirection ends, because the value
+/// appended may in fact be the string we write to, changing it may cause freed
+/// memory to be used:
+///   :redir => foo
+///   :let foo
+///   :redir END
 void var_redir_str(char_u *value, int value_len)
 {
   int len;
@@ -614,10 +609,8 @@ void var_redir_str(char_u *value, int value_len)
   redir_ga.ga_len += len;
 }
 
-/*
- * Stop redirecting command output to a variable.
- * Frees the allocated memory.
- */
+/// Stop redirecting command output to a variable.
+/// Frees the allocated memory.
 void var_redir_stop(void)
 {
   typval_T tv;
@@ -744,7 +737,7 @@ int eval_to_bool(char_u *arg, bool *error, char_u **nextcmd, int skip)
   return retval;
 }
 
-// Call eval1() and give an error message if not done at a lower level.
+/// Call eval1() and give an error message if not done at a lower level.
 static int eval1_emsg(char_u **arg, typval_T *rettv, bool evaluate)
   FUNC_ATTR_NONNULL_ARG(1, 2)
 {
@@ -767,8 +760,8 @@ static int eval1_emsg(char_u **arg, typval_T *rettv, bool evaluate)
   return ret;
 }
 
-/// @return whether a typval is a valid expression to pass to eval_expr_typval()
-/// or eval_expr_to_bool().  An empty string returns false;
+/// @return  whether a typval is a valid expression to pass to eval_expr_typval()
+///          or eval_expr_to_bool().  An empty string returns false;
 bool eval_expr_valid_arg(const typval_T *const tv)
   FUNC_ATTR_NONNULL_ALL FUNC_ATTR_CONST
 {
@@ -867,10 +860,9 @@ char *eval_to_string_skip(const char *arg, const char **nextcmd, const bool skip
   return retval;
 }
 
-/*
- * Skip over an expression at "*pp".
- * Return FAIL for an error, OK otherwise.
- */
+/// Skip over an expression at "*pp".
+///
+/// @return  FAIL for an error, OK otherwise.
 int skip_expr(char_u **pp)
 {
   typval_T rettv;
@@ -917,10 +909,10 @@ char_u *eval_to_string(char_u *arg, char_u **nextcmd, bool convert)
   return (char_u *)retval;
 }
 
-/*
- * Call eval_to_string() without using current local variables and using
- * textlock.  When "use_sandbox" is TRUE use the sandbox.
- */
+/// Call eval_to_string() without using current local variables and using
+/// textlock.
+///
+/// @param use_sandbox  when TRUE, use the sandbox.
 char_u *eval_to_string_safe(char_u *arg, char_u **nextcmd, int use_sandbox)
 {
   char_u *retval;
@@ -940,11 +932,10 @@ char_u *eval_to_string_safe(char_u *arg, char_u **nextcmd, int use_sandbox)
   return retval;
 }
 
-/*
- * Top level evaluation function, returning a number.
- * Evaluates "expr" silently.
- * Returns -1 for an error.
- */
+/// Top level evaluation function, returning a number.
+/// Evaluates "expr" silently.
+///
+/// @return  -1 for an error.
 varnumber_T eval_to_number(char_u *expr)
 {
   typval_T rettv;
@@ -964,9 +955,10 @@ varnumber_T eval_to_number(char_u *expr)
   return retval;
 }
 
-// Top level evaluation function.
-// Returns an allocated typval_T with the result.
-// Returns NULL when there is an error.
+/// Top level evaluation function.
+///
+/// @return  an allocated typval_T with the result or
+///          NULL when there is an error.
 typval_T *eval_expr(char_u *arg)
 {
   typval_T *tv = xmalloc(sizeof(*tv));
@@ -976,11 +968,9 @@ typval_T *eval_expr(char_u *arg)
   return tv;
 }
 
-/*
- * Prepare v: variable "idx" to be used.
- * Save the current typeval in "save_tv".
- * When not used yet add the variable to the v: hashtable.
- */
+/// Prepare v: variable "idx" to be used.
+/// Save the current typeval in "save_tv".
+/// When not used yet add the variable to the v: hashtable.
 void prepare_vimvar(int idx, typval_T *save_tv)
 {
   *save_tv = vimvars[idx].vv_tv;
@@ -989,10 +979,8 @@ void prepare_vimvar(int idx, typval_T *save_tv)
   }
 }
 
-/*
- * Restore v: variable "idx" to typeval "save_tv".
- * When no longer defined, remove the variable from the v: hashtable.
- */
+/// Restore v: variable "idx" to typeval "save_tv".
+/// When no longer defined, remove the variable from the v: hashtable.
 void restore_vimvar(int idx, typval_T *save_tv)
 {
   hashitem_T *hi;
@@ -1019,11 +1007,10 @@ void find_win_for_curbuf(void)
   }
 }
 
-/*
- * Evaluate an expression to a list with suggestions.
- * For the "expr:" part of 'spellsuggest'.
- * Returns NULL when there is an error.
- */
+/// Evaluate an expression to a list with suggestions.
+/// For the "expr:" part of 'spellsuggest'.
+///
+/// @return  NULL when there is an error.
 list_T *eval_spell_expr(char_u *badword, char_u *expr)
 {
   typval_T save_val;
@@ -1087,7 +1074,7 @@ int get_spellword(list_T *const list, const char **ret_word)
 // Uses argv[0] to argv[argc-1] for the function arguments. argv[argc]
 // should have type VAR_UNKNOWN.
 //
-// Return OK or FAIL.
+// @return  OK or FAIL.
 int call_vim_function(const char_u *func, int argc, typval_T *argv, typval_T *rettv)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -1225,10 +1212,8 @@ void prof_child_exit(proftime_T *tm)
 }
 
 
-/*
- * Evaluate 'foldexpr'.  Returns the foldlevel, and any character preceding
- * it in "*cp".  Doesn't give error messages.
- */
+/// Evaluate 'foldexpr'.  Returns the foldlevel, and any character preceding
+/// it in "*cp".  Doesn't give error messages.
 int eval_foldexpr(char_u *arg, int *cp)
 {
   typval_T tv;
@@ -1269,26 +1254,27 @@ int eval_foldexpr(char_u *arg, int *cp)
   return (int)retval;
 }
 
-// ":cons[t] var = expr1" define constant
-// ":cons[t] [name1, name2, ...] = expr1" define constants unpacking list
-// ":cons[t] [name, ..., ; lastname] = expr" define constants unpacking list
+/// ":cons[t] var = expr1" define constant
+/// ":cons[t] [name1, name2, ...] = expr1" define constants unpacking list
+/// ":cons[t] [name, ..., ; lastname] = expr" define constants unpacking list
 void ex_const(exarg_T *eap)
 {
   ex_let_const(eap, true);
 }
 
-// Get a list of lines from a HERE document. The here document is a list of
-// lines surrounded by a marker.
-//     cmd << {marker}
-//       {line1}
-//       {line2}
-//       ....
-//     {marker}
-//
-// The {marker} is a string. If the optional 'trim' word is supplied before the
-// marker, then the leading indentation before the lines (matching the
-// indentation in the 'cmd' line) is stripped.
-// Returns a List with {lines} or NULL.
+/// Get a list of lines from a HERE document. The here document is a list of
+/// lines surrounded by a marker.
+///     cmd << {marker}
+///       {line1}
+///       {line2}
+///       ....
+///     {marker}
+///
+/// The {marker} is a string. If the optional 'trim' word is supplied before the
+/// marker, then the leading indentation before the lines (matching the
+/// indentation in the 'cmd' line) is stripped.
+///
+/// @return  a List with {lines} or NULL.
 static list_T *heredoc_get(exarg_T *eap, char_u *cmd)
 {
   char_u *marker;
@@ -1386,18 +1372,18 @@ static list_T *heredoc_get(exarg_T *eap, char_u *cmd)
   return l;
 }
 
-// ":let" list all variable values
-// ":let var1 var2" list variable values
-// ":let var = expr" assignment command.
-// ":let var += expr" assignment command.
-// ":let var -= expr" assignment command.
-// ":let var *= expr" assignment command.
-// ":let var /= expr" assignment command.
-// ":let var %= expr" assignment command.
-// ":let var .= expr" assignment command.
-// ":let var ..= expr" assignment command.
-// ":let [var1, var2] = expr" unpack list.
-// ":let [name, ..., ; lastname] = expr" unpack list.
+/// ":let" list all variable values
+/// ":let var1 var2" list variable values
+/// ":let var = expr" assignment command.
+/// ":let var += expr" assignment command.
+/// ":let var -= expr" assignment command.
+/// ":let var *= expr" assignment command.
+/// ":let var /= expr" assignment command.
+/// ":let var %= expr" assignment command.
+/// ":let var .= expr" assignment command.
+/// ":let var ..= expr" assignment command.
+/// ":let [var1, var2] = expr" unpack list.
+/// ":let [name, ..., ; lastname] = expr" unpack list.
 void ex_let(exarg_T *eap)
 {
   ex_let_const(eap, false);
@@ -1578,13 +1564,12 @@ static int ex_let_vars(char_u *arg_start, typval_T *tv, int copy, int semicolon,
   return OK;
 }
 
-/*
- * Skip over assignable variable "var" or list of variables "[var, var]".
- * Used for ":let varvar = expr" and ":for varvar in expr".
- * For "[var, var]" increment "*var_count" for each variable.
- * for "[var, var; var]" set "semicolon".
- * Return NULL for an error.
- */
+/// Skip over assignable variable "var" or list of variables "[var, var]".
+/// Used for ":let varvar = expr" and ":for varvar in expr".
+/// For "[var, var]" increment "*var_count" for each variable.
+/// for "[var, var; var]" set "semicolon".
+///
+/// @return  NULL for an error.
 static const char_u *skip_var_list(const char_u *arg, int *var_count, int *semicolon)
 {
   const char_u *p;
@@ -1622,10 +1607,8 @@ static const char_u *skip_var_list(const char_u *arg, int *var_count, int *semic
   }
 }
 
-/*
- * Skip one (assignable) variable name, including @r, $VAR, &option, d.key,
- * l[idx].
- */
+/// Skip one (assignable) variable name, including @r, $VAR, &option, d.key,
+/// l[idx].
 static const char_u *skip_var_one(const char_u *arg)
 {
   if (*arg == '@' && arg[1] != NUL) {
@@ -1635,10 +1618,9 @@ static const char_u *skip_var_one(const char_u *arg)
                        NULL, NULL, FNE_INCL_BR | FNE_CHECK_START);
 }
 
-/*
- * List variables for hashtab "ht" with prefix "prefix".
- * If "empty" is TRUE also list NULL strings as empty strings.
- */
+/// List variables for hashtab "ht" with prefix "prefix".
+///
+/// @param empty  if TRUE also list NULL strings as empty strings.
 void list_hashtable_vars(hashtab_T *ht, const char *prefix, int empty, int *first)
 {
   hashitem_T *hi;
@@ -1667,47 +1649,37 @@ void list_hashtable_vars(hashtab_T *ht, const char *prefix, int empty, int *firs
   }
 }
 
-/*
- * List global variables.
- */
+/// List global variables.
 static void list_glob_vars(int *first)
 {
   list_hashtable_vars(&globvarht, "", true, first);
 }
 
-/*
- * List buffer variables.
- */
+/// List buffer variables.
 static void list_buf_vars(int *first)
 {
   list_hashtable_vars(&curbuf->b_vars->dv_hashtab, "b:", true, first);
 }
 
-/*
- * List window variables.
- */
+/// List window variables.
 static void list_win_vars(int *first)
 {
   list_hashtable_vars(&curwin->w_vars->dv_hashtab, "w:", true, first);
 }
 
-/*
- * List tab page variables.
- */
+/// List tab page variables.
 static void list_tab_vars(int *first)
 {
   list_hashtable_vars(&curtab->tp_vars->dv_hashtab, "t:", true, first);
 }
 
-/*
- * List Vim variables.
- */
+/// List Vim variables.
 static void list_vim_vars(int *first)
 {
   list_hashtable_vars(&vimvarht, "v:", false, first);
 }
 
-// List script-local variables, if there is a script.
+/// List script-local variables, if there is a script.
 static void list_script_vars(int *first)
 {
   if (current_sctx.sc_sid > 0 && current_sctx.sc_sid <= ga_scripts.ga_len) {
@@ -1715,9 +1687,7 @@ static void list_script_vars(int *first)
   }
 }
 
-/*
- * List variables in "arg".
- */
+/// List variables in "arg".
 static const char *list_arg_vars(exarg_T *eap, const char *arg, int *first)
 {
   int error = FALSE;
@@ -2380,9 +2350,7 @@ char_u *get_lval(char_u *const name, typval_T *const rettv, lval_T *const lp, co
 
 // TODO(ZyX-I): move to eval/executor
 
-/*
- * Clear lval "lp" that was filled by get_lval().
- */
+/// Clear lval "lp" that was filled by get_lval().
 void clear_lval(lval_T *lp)
 {
   xfree(lp->ll_exp_name);
@@ -2391,12 +2359,11 @@ void clear_lval(lval_T *lp)
 
 // TODO(ZyX-I): move to eval/executor
 
-/*
- * Set a variable that was parsed by get_lval() to "rettv".
- * "endp" points to just after the parsed name.
- * "op" is NULL, "+" for "+=", "-" for "-=", "*" for "*=", "/" for "/=",
- * "%" for "%=", "." for ".=" or "=" for "=".
- */
+/// Set a variable that was parsed by get_lval() to "rettv".
+///
+/// @param endp  points to just after the parsed name.
+/// @param op    NULL, "+" for "+=", "-" for "-=", "*" for "*=", "/" for "/=",
+///              "%" for "%=", "." for ".=" or "=" for "=".
 static void set_var_lval(lval_T *lp, char_u *endp, typval_T *rettv, int copy, const bool is_const,
                          const char *op)
 {
@@ -2599,12 +2566,12 @@ notify:
 
 // TODO(ZyX-I): move to eval/ex_cmds
 
-/*
- * Evaluate the expression used in a ":for var in expr" command.
- * "arg" points to "var".
- * Set "*errp" to TRUE for an error, FALSE otherwise;
- * Return a pointer that holds the info.  Null when there is an error.
- */
+/// Evaluate the expression used in a ":for var in expr" command.
+/// "arg" points to "var".
+///
+/// @param[out] *errp  set to TRUE for an error, FALSE otherwise;
+///
+/// @return  a pointer that holds the info.  Null when there is an error.
 void *eval_for_line(const char_u *arg, bool *errp, char_u **nextcmdp, int skip)
 {
   forinfo_T *fi = xcalloc(1, sizeof(forinfo_T));
@@ -2676,12 +2643,11 @@ void *eval_for_line(const char_u *arg, bool *errp, char_u **nextcmdp, int skip)
 
 // TODO(ZyX-I): move to eval/ex_cmds
 
-/*
- * Use the first item in a ":for" list.  Advance to the next.
- * Assign the values to the variable (list).  "arg" points to the first one.
- * Return TRUE when a valid item was found, FALSE when at end of list or
- * something wrong.
- */
+/// Use the first item in a ":for" list.  Advance to the next.
+/// Assign the values to the variable (list).  "arg" points to the first one.
+///
+/// @return  true when a valid item was found, false when at end of list or
+///          something wrong.
 bool next_for_item(void *fi_void, char_u *arg)
 {
   forinfo_T *fi = (forinfo_T *)fi_void;
@@ -2727,9 +2693,7 @@ bool next_for_item(void *fi_void, char_u *arg)
 
 // TODO(ZyX-I): move to eval/ex_cmds
 
-/*
- * Free the structure used to store info used by ":for".
- */
+/// Free the structure used to store info used by ":for".
 void free_for_info(void *fi_void)
 {
   forinfo_T *fi = (forinfo_T *)fi_void;
@@ -3178,9 +3142,7 @@ static int do_lock_var(lval_T *lp, char_u *name_end FUNC_ATTR_UNUSED, exarg_T *e
   return ret;
 }
 
-/*
- * Delete all "menutrans_" variables.
- */
+/// Delete all "menutrans_" variables.
 void del_menutrans_vars(void)
 {
   hash_lock(&globvarht);
@@ -3202,9 +3164,7 @@ void del_menutrans_vars(void)
 static char_u *varnamebuf = NULL;
 static size_t varnamebuflen = 0;
 
-/*
- * Function to concatenate a prefix and a variable name.
- */
+/// Function to concatenate a prefix and a variable name.
 char_u *cat_prefix_varname(int prefix, const char_u *name)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -3222,10 +3182,8 @@ char_u *cat_prefix_varname(int prefix, const char_u *name)
   return varnamebuf;
 }
 
-/*
- * Function given to ExpandGeneric() to obtain the list of user defined
- * (global/buffer/window/built-in) variable names.
- */
+/// Function given to ExpandGeneric() to obtain the list of user defined
+/// (global/buffer/window/built-in) variable names.
 char_u *get_user_var_name(expand_T *xp, int idx)
 {
   static size_t gdone;
@@ -3313,8 +3271,9 @@ char_u *get_user_var_name(expand_T *xp, int idx)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/// Return TRUE if "pat" matches "text".
 /// Does not use 'cpo' and always uses 'magic'.
+///
+/// @return  TRUE if "pat" matches "text".
 static int pattern_match(char_u *pat, char_u *text, bool ic)
 {
   int matches = 0;
@@ -3335,10 +3294,10 @@ static int pattern_match(char_u *pat, char_u *text, bool ic)
 
 /// Handle a name followed by "(".  Both for just "name(arg)" and for
 /// "expr->name(arg)".
-//
+///
 /// @param arg  Points to "(", will be advanced
 /// @param basetv  "expr" for "expr->name(arg)"
-//
+///
 /// @return OK or FAIL.
 static int eval_func(char_u **const arg, char_u *const name, const int name_len,
                      typval_T *const rettv, const bool evaluate, typval_T *const basetv)
@@ -3399,13 +3358,12 @@ static int eval_func(char_u **const arg, char_u *const name, const int name_len,
  * VAR_UNKNOWN.  The function still returns FAIL for a syntax error.
  */
 
-/*
- * Handle zero level expression.
- * This calls eval1() and handles error message and nextcmd.
- * Put the result in "rettv" when returning OK and "evaluate" is TRUE.
- * Note: "rettv.v_lock" is not set.
- * Return OK or FAIL.
- */
+/// Handle zero level expression.
+/// This calls eval1() and handles error message and nextcmd.
+/// Put the result in "rettv" when returning OK and "evaluate" is TRUE.
+/// Note: "rettv.v_lock" is not set.
+///
+/// @return OK or FAIL.
 int eval0(char_u *arg, typval_T *rettv, char_u **nextcmd, int evaluate)
 {
   int ret;
@@ -3438,17 +3396,15 @@ int eval0(char_u *arg, typval_T *rettv, char_u **nextcmd, int evaluate)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/*
- * Handle top level expression:
- *      expr2 ? expr1 : expr1
- *
- * "arg" must point to the first non-white of the expression.
- * "arg" is advanced to the next non-white after the recognized expression.
- *
- * Note: "rettv.v_lock" is not set.
- *
- * Return OK or FAIL.
- */
+/// Handle top level expression:
+///      expr2 ? expr1 : expr1
+///
+/// "arg" must point to the first non-white of the expression.
+/// "arg" is advanced to the next non-white after the recognized expression.
+///
+/// Note: "rettv.v_lock" is not set.
+///
+/// @return  OK or FAIL.
 int eval1(char_u **arg, typval_T *rettv, int evaluate)
 {
   int result;
@@ -3514,15 +3470,13 @@ int eval1(char_u **arg, typval_T *rettv, int evaluate)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/*
- * Handle first level expression:
- *      expr2 || expr2 || expr2     logical OR
- *
- * "arg" must point to the first non-white of the expression.
- * "arg" is advanced to the next non-white after the recognized expression.
- *
- * Return OK or FAIL.
- */
+/// Handle first level expression:
+///      expr2 || expr2 || expr2     logical OR
+///
+/// "arg" must point to the first non-white of the expression.
+/// "arg" is advanced to the next non-white after the recognized expression.
+///
+/// @return  OK or FAIL.
 static int eval2(char_u **arg, typval_T *rettv, int evaluate)
 {
   typval_T var2;
@@ -3585,15 +3539,13 @@ static int eval2(char_u **arg, typval_T *rettv, int evaluate)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/*
- * Handle second level expression:
- *      expr3 && expr3 && expr3     logical AND
- *
- * "arg" must point to the first non-white of the expression.
- * "arg" is advanced to the next non-white after the recognized expression.
- *
- * Return OK or FAIL.
- */
+/// Handle second level expression:
+///      expr3 && expr3 && expr3     logical AND
+///
+/// @param arg  must point to the first non-white of the expression.
+///             `arg` is advanced to the next non-white after the recognized expression.
+///
+/// @return  OK or FAIL.
 static int eval3(char_u **arg, typval_T *rettv, int evaluate)
 {
   typval_T var2;
@@ -3656,24 +3608,22 @@ static int eval3(char_u **arg, typval_T *rettv, int evaluate)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/*
- * Handle third level expression:
- *      var1 == var2
- *      var1 =~ var2
- *      var1 != var2
- *      var1 !~ var2
- *      var1 > var2
- *      var1 >= var2
- *      var1 < var2
- *      var1 <= var2
- *      var1 is var2
- *      var1 isnot var2
- *
- * "arg" must point to the first non-white of the expression.
- * "arg" is advanced to the next non-white after the recognized expression.
- *
- * Return OK or FAIL.
- */
+/// Handle third level expression:
+///      var1 == var2
+///      var1 =~ var2
+///      var1 != var2
+///      var1 !~ var2
+///      var1 > var2
+///      var1 >= var2
+///      var1 < var2
+///      var1 <= var2
+///      var1 is var2
+///      var1 isnot var2
+///
+/// "arg" must point to the first non-white of the expression.
+/// "arg" is advanced to the next non-white after the recognized expression.
+///
+/// @return  OK or FAIL.
 static int eval4(char_u **arg, typval_T *rettv, int evaluate)
 {
   typval_T var2;
@@ -3767,18 +3717,16 @@ static int eval4(char_u **arg, typval_T *rettv, int evaluate)
 
 // TODO(ZyX-I): move to eval/expressions
 
-/*
- * Handle fourth level expression:
- *      +       number addition
- *      -       number subtraction
- *      .       string concatenation
- *      ..      string concatenation
- *
- * "arg" must point to the first non-white of the expression.
- * "arg" is advanced to the next non-white after the recognized expression.
- *
- * Return OK or FAIL.
- */
+/// Handle fourth level expression:
+///      +       number addition
+///      -       number subtraction
+///      .       string concatenation
+///      ..      string concatenation
+///
+/// @param arg  must point to the first non-white of the expression.
+///             `arg` is advanced to the next non-white after the recognized expression.
+///
+/// @return  OK or FAIL.
 static int eval5(char_u **arg, typval_T *rettv, int evaluate)
 {
   typval_T var2;
@@ -4324,7 +4272,8 @@ static int eval7(char_u **arg, typval_T *rettv, int evaluate, int want_string)
 
 /// Apply the leading "!" and "-" before an eval7 expression to "rettv".
 /// Adjusts "end_leaderp" until it is at "start_leader".
-/// @return OK on success, FAIL on failure.
+///
+/// @return  OK on success, FAIL on failure.
 static int eval7_leader(typval_T *const rettv, const char_u *const start_leader,
                         const char_u **const end_leaderp)
   FUNC_ATTR_NONNULL_ALL
@@ -4378,7 +4327,7 @@ static int eval7_leader(typval_T *const rettv, const char_u *const start_leader,
 /// @param lua_funcname  If `rettv` refers to a v:lua function, this must point
 ///                      to the name of the Lua function to call (after the
 ///                      "v:lua." prefix).
-/// @return OK on success, FAIL on failure.
+/// @return  OK on success, FAIL on failure.
 static int call_func_rettv(char_u **const arg, typval_T *const rettv, const bool evaluate,
                            dict_T *const selfdict, typval_T *const basetv,
                            const char_u *const lua_funcname)
@@ -4426,9 +4375,13 @@ static int call_func_rettv(char_u **const arg, typval_T *const rettv, const bool
 }
 
 /// Evaluate "->method()".
+///
 /// @param verbose  if true, give error messages.
-/// @note "*arg" points to the '-'.
-/// @return FAIL or OK. @note "*arg" is advanced to after the ')'.
+/// @param *arg     points to the '-'.
+///
+/// @return  FAIL or OK.
+///
+/// @note "*arg" is advanced to after the ')'.
 static int eval_lambda(char_u **const arg, typval_T *const rettv, const bool evaluate,
                        const bool verbose)
   FUNC_ATTR_NONNULL_ALL
@@ -4465,8 +4418,10 @@ static int eval_lambda(char_u **const arg, typval_T *const rettv, const bool eva
 }
 
 /// Evaluate "->method()" or "->v:lua.method()".
-/// @note "*arg" points to the '-'.
-/// @return FAIL or OK. "*arg" is advanced to after the ')'.
+///
+/// @param *arg  points to the '-'.
+///
+/// @return  FAIL or OK. "*arg" is advanced to after the ')'.
 static int eval_method(char_u **const arg, typval_T *const rettv, const bool evaluate,
                        const bool verbose)
   FUNC_ATTR_NONNULL_ALL
@@ -4539,9 +4494,10 @@ static int eval_method(char_u **const arg, typval_T *const rettv, const bool eva
 
 /// Evaluate an "[expr]" or "[expr:expr]" index.  Also "dict.key".
 /// "*arg" points to the '[' or '.'.
-/// Returns FAIL or OK. "*arg" is advanced to after the ']'.
 ///
 /// @param verbose  give error messages
+///
+/// @returns FAIL or OK. "*arg" is advanced to after the ']'.
 static int eval_index(char_u **arg, typval_T *rettv, int evaluate, int verbose)
 {
   bool empty1 = false;
@@ -4846,12 +4802,12 @@ static int eval_index(char_u **arg, typval_T *rettv, int evaluate, int verbose)
 
 /// Get an option value
 ///
-/// @param[in,out]  arg  Points to the '&' or '+' before the option name. Is
+/// @param[in,out] arg  Points to the '&' or '+' before the option name. Is
 ///                      advanced to the character after the option name.
-/// @param[out]  rettv  Location where result is saved.
-/// @param[in]  evaluate  If not true, rettv is not populated.
+/// @param[out] rettv  Location where result is saved.
+/// @param[in] evaluate  If not true, rettv is not populated.
 ///
-/// @return OK or FAIL.
+/// @return  OK or FAIL.
 int get_option_tv(const char **const arg, typval_T *const rettv, const bool evaluate)
   FUNC_ATTR_NONNULL_ARG(1)
 {
@@ -4910,10 +4866,9 @@ int get_option_tv(const char **const arg, typval_T *const rettv, const bool eval
   return ret;
 }
 
-/*
- * Allocate a variable for a string constant.
- * Return OK or FAIL.
- */
+/// Allocate a variable for a string constant.
+///
+/// @return  OK or FAIL.
 static int get_string_tv(char_u **arg, typval_T *rettv, int evaluate)
 {
   char_u *p;
@@ -5050,10 +5005,9 @@ static int get_string_tv(char_u **arg, typval_T *rettv, int evaluate)
   return OK;
 }
 
-/*
- * Allocate a variable for a 'str''ing' constant.
- * Return OK or FAIL.
- */
+/// Allocate a variable for a 'str''ing' constant.
+///
+/// @return  OK or FAIL.
 static int get_lit_string_tv(char_u **arg, typval_T *rettv, int evaluate)
 {
   char_u *p;
@@ -5106,7 +5060,7 @@ static int get_lit_string_tv(char_u **arg, typval_T *rettv, int evaluate)
   return OK;
 }
 
-/// @return the function name of the partial.
+/// @return  the function name of the partial.
 char_u *partial_name(partial_T *pt)
 {
   if (pt->pt_name != NULL) {
@@ -5145,7 +5099,8 @@ void partial_unref(partial_T *pt)
 }
 
 /// Allocate a variable for a List and fill it from "*arg".
-/// Return OK or FAIL.
+///
+/// @return  OK or FAIL.
 static int get_list_tv(char_u **arg, typval_T *rettv, int evaluate)
 {
   list_T *l = NULL;
@@ -5283,7 +5238,8 @@ int get_copyID(void)
 /// Do garbage collection for lists and dicts.
 ///
 /// @param testing  true if called from test_garbagecollect_now().
-/// @returns        true if some memory was freed.
+///
+/// @return  true if some memory was freed.
 bool garbage_collect(bool testing)
 {
   bool abort = false;
@@ -5461,10 +5417,11 @@ bool garbage_collect(bool testing)
 
 /// Free lists and dictionaries that are no longer referenced.
 ///
-/// @note This function may only be called from garbage_collect().
+/// @note  This function may only be called from garbage_collect().
 ///
-/// @param copyID Free lists/dictionaries that don't have this ID.
-/// @return true, if something was freed.
+/// @param copyID  Free lists/dictionaries that don't have this ID.
+///
+/// @return  true, if something was freed.
 static int free_unref_items(int copyID)
 {
   bool did_free = false;
@@ -5699,7 +5656,7 @@ bool set_ref_in_item(typval_T *tv, int copyID, ht_stack_T **ht_stack, list_stack
 
 /// Mark all lists and dicts referenced in given mark
 ///
-/// @returns true if setting references failed somehow.
+/// @return  true if setting references failed somehow.
 static inline bool set_ref_in_fmark(fmark_T fm, int copyID)
   FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -5713,7 +5670,7 @@ static inline bool set_ref_in_fmark(fmark_T fm, int copyID)
 
 /// Mark all lists and dicts referenced in given list and the list itself
 ///
-/// @returns true if setting references failed somehow.
+/// @return  true if setting references failed somehow.
 static inline bool set_ref_list(list_T *list, int copyID)
   FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -5729,7 +5686,7 @@ static inline bool set_ref_list(list_T *list, int copyID)
 
 /// Mark all lists and dicts referenced in given dict and the dict itself
 ///
-/// @returns true if setting references failed somehow.
+/// @return  true if setting references failed somehow.
 static inline bool set_ref_dict(dict_T *dict, int copyID)
   FUNC_ATTR_WARN_UNUSED_RESULT
 {
@@ -5744,8 +5701,9 @@ static inline bool set_ref_dict(dict_T *dict, int copyID)
 }
 
 
-// Get the key for *{key: val} into "tv" and advance "arg".
-// Return FAIL when there is no valid key.
+/// Get the key for *{key: val} into "tv" and advance "arg".
+///
+/// @return  FAIL when there is no valid key.
 static int get_literal_key(char_u **arg, typval_T *tv)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -5763,9 +5721,10 @@ static int get_literal_key(char_u **arg, typval_T *tv)
   return OK;
 }
 
-// Allocate a variable for a Dictionary and fill it from "*arg".
-// "literal" is true for *{key: val}
-// Return OK or FAIL.  Returns NOTDONE for {expr}.
+/// Allocate a variable for a Dictionary and fill it from "*arg".
+/// "literal" is true for *{key: val}
+///
+/// @return  OK or FAIL.  Returns NOTDONE for {expr}.
 static int dict_get_tv(char_u **arg, typval_T *rettv, int evaluate, bool literal)
 {
   dict_T *d = NULL;
@@ -5875,10 +5834,10 @@ failret:
 /// This uses strtod().  setlocale(LC_NUMERIC, "C") has been used earlier to
 /// make sure this always uses a decimal point.
 ///
-/// @param[in]  text  String to convert.
-/// @param[out]  ret_value  Location where conversion result is saved.
+/// @param[in] text  String to convert.
+/// @param[out] ret_value  Location where conversion result is saved.
 ///
-/// @return Length of the text that was consumed.
+/// @return  Length of the text that was consumed.
 size_t string2float(const char *const text, float_T *const ret_value)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -5905,9 +5864,9 @@ size_t string2float(const char *const text, float_T *const ret_value)
 ///
 /// If the environment variable was not set, silently assume it is empty.
 ///
-/// @param arg Points to the '$'.  It is advanced to after the name.
-/// @return FAIL if the name is invalid.
+/// @param arg  Points to the '$'.  It is advanced to after the name.
 ///
+/// @return  FAIL if the name is invalid.
 static int get_env_tv(char_u **arg, typval_T *rettv, int evaluate)
 {
   char_u *name;
@@ -5956,7 +5915,7 @@ void get_arglist_as_rettv(aentry_T *arglist, int argcount, typval_T *rettv)
   }
 }
 
-// Prepare "gap" for an assert error and add the sourcing position.
+/// Prepare "gap" for an assert error and add the sourcing position.
 void prepare_assert_error(garray_T *gap)
 {
   char buf[NUMBUFLEN];
@@ -5977,8 +5936,8 @@ void prepare_assert_error(garray_T *gap)
   }
 }
 
-// Append "p[clen]" to "gap", escaping unprintable characters.
-// Changes NL to \n, CR to \r, etc.
+/// Append "p[clen]" to "gap", escaping unprintable characters.
+/// Changes NL to \n, CR to \r, etc.
 static void ga_concat_esc(garray_T *gap, const char_u *p, int clen)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -6016,8 +5975,8 @@ static void ga_concat_esc(garray_T *gap, const char_u *p, int clen)
   }
 }
 
-// Append "str" to "gap", escaping unprintable characters.
-// Changes NL to \n, CR to \r, etc.
+/// Append "str" to "gap", escaping unprintable characters.
+/// Changes NL to \n, CR to \r, etc.
 static void ga_concat_shorten_esc(garray_T *gap, const char_u *str)
   FUNC_ATTR_NONNULL_ARG(1)
 {
@@ -6051,7 +6010,7 @@ static void ga_concat_shorten_esc(garray_T *gap, const char_u *str)
   }
 }
 
-// Fill "gap" with information about an assert error.
+/// Fill "gap" with information about an assert error.
 void fill_assert_error(garray_T *gap, typval_T *opt_msg_tv, char_u *exp_str, typval_T *exp_tv,
                        typval_T *got_tv, assert_type_T atype)
 {
@@ -6094,7 +6053,7 @@ void fill_assert_error(garray_T *gap, typval_T *opt_msg_tv, char_u *exp_str, typ
   }
 }
 
-// Add an assert error to v:errors.
+/// Add an assert error to v:errors.
 void assert_error(garray_T *gap)
 {
   struct vimvar *vp = &vimvars[VV_ERRORS];
@@ -6268,7 +6227,7 @@ int assert_inrange(typval_T *argvars)
   return 0;
 }
 
-// Common for assert_true() and assert_false().
+/// Common for assert_true() and assert_false().
 int assert_bool(typval_T *argvars, bool is_true)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -6442,9 +6401,7 @@ win_T *find_win_by_nr_or_id(typval_T *vp)
   return find_win_by_nr(vp, NULL);
 }
 
-/*
- * Implementation of map() and filter().
- */
+/// Implementation of map() and filter().
 void filter_map(typval_T *argvars, typval_T *rettv, int map)
 {
   typval_T *expr;
@@ -6806,7 +6763,7 @@ theend:
   xfree(trans_name);
 }
 
-/// Returns buffer options, variables and other attributes in a dictionary.
+/// @return  buffer options, variables and other attributes in a dictionary.
 dict_T *get_buffer_info(buf_T *buf)
 {
   dict_T *const dict = tv_dict_alloc();
@@ -6850,12 +6807,12 @@ dict_T *get_buffer_info(buf_T *buf)
 ///
 /// @note Unlike tv_get_lnum(), this one supports only "$" special string.
 ///
-/// @param[in]  tv  Object to get value from. Is expected to be a