refactor(eval/funcs): convert function comments to doxygen format

1 files changed, 314 insertions, 711 deletions

diff --git a/src/nvim/eval/funcs.c b/src/nvim/eval/funcs.c
index c8abbff933..b249dffe11 100644
--- a/src/nvim/eval/funcs.c
+++ b/src/nvim/eval/funcs.c
@@ -175,7 +175,7 @@ char_u *get_expr_name(expand_T *xp, int idx)
 ///
 /// @param[in]  name  Name of the function.
 ///
-/// Returns pointer to the function definition or NULL if not found.
+/// @return  pointer to the function definition or NULL if not found.
 const VimLFuncDef *find_internal_func(const char *const name)
   FUNC_ATTR_WARN_UNUSED_RESULT FUNC_ATTR_PURE FUNC_ATTR_NONNULL_ALL
 {
@@ -229,9 +229,7 @@ int call_internal_method(const char_u *const fname, const int argcount, typval_T
   return ERROR_NONE;
 }
 
-/*
- * Return TRUE for a non-zero Number and a non-empty String.
- */
+/// @return  TRUE for a non-zero Number and a non-empty String.
 static int non_zero_arg(typval_T *argvars)
 {
   return ((argvars[0].v_type == VAR_NUMBER
@@ -243,11 +241,11 @@ static int non_zero_arg(typval_T *argvars)
               && *argvars[0].vval.v_string != NUL));
 }
 
-// Apply a floating point C function on a typval with one float_T.
-//
-// Some versions of glibc on i386 have an optimization that makes it harder to
-// call math functions indirectly from inside an inlined function, causing
-// compile-time errors. Avoid `inline` in that case. #3072
+/// Apply a floating point C function on a typval with one float_T.
+///
+/// Some versions of glibc on i386 have an optimization that makes it harder to
+/// call math functions indirectly from inside an inlined function, causing
+/// compile-time errors. Avoid `inline` in that case. #3072
 static void float_op_wrapper(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   float_T f;
@@ -293,9 +291,7 @@ end:
   api_clear_error(&err);
 }
 
-/*
- * "abs(expr)" function
- */
+/// "abs(expr)" function
 static void f_abs(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if (argvars[0].v_type == VAR_FLOAT) {
@@ -315,9 +311,7 @@ static void f_abs(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "add(list, item)" function
- */
+/// "add(list, item)" function
 static void f_add(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = 1;  // Default: failed.
@@ -345,9 +339,7 @@ static void f_add(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "and(expr, expr)" function
- */
+/// "and(expr, expr)" function
 static void f_and(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = tv_get_number_chk(&argvars[0], NULL)
@@ -363,7 +355,7 @@ static void f_api_info(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   api_free_dictionary(metadata);
 }
 
-// "append(lnum, string/list)" function
+/// "append(lnum, string/list)" function
 static void f_append(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const linenr_T lnum = tv_get_lnum(&argvars[0]);
@@ -371,7 +363,7 @@ static void f_append(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   set_buffer_lines(curbuf, lnum, true, &argvars[1], rettv);
 }
 
-// "appendbufline(buf, lnum, string/list)" function
+/// "appendbufline(buf, lnum, string/list)" function
 static void f_appendbufline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   buf_T *const buf = tv_get_buf(&argvars[0], false);
@@ -403,9 +395,7 @@ static void f_argc(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "argidx()" function
- */
+/// "argidx()" function
 static void f_argidx(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = curwin->w_arg_idx;
@@ -421,9 +411,7 @@ static void f_arglistid(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "argv(nr)" function
- */
+/// "argv(nr)" function
 static void f_argv(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   aentry_T *arglist = NULL;
@@ -458,31 +446,31 @@ static void f_argv(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "assert_beeps(cmd [, error])" function
+/// "assert_beeps(cmd [, error])" function
 static void f_assert_beeps(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_beeps(argvars, false);
 }
 
-// "assert_nobeep(cmd [, error])" function
+/// "assert_nobeep(cmd [, error])" function
 static void f_assert_nobeep(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_beeps(argvars, true);
 }
 
-// "assert_equal(expected, actual[, msg])" function
+/// "assert_equal(expected, actual[, msg])" function
 static void f_assert_equal(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_equal_common(argvars, ASSERT_EQUAL);
 }
 
-// "assert_equalfile(fname-one, fname-two[, msg])" function
+/// "assert_equalfile(fname-one, fname-two[, msg])" function
 static void f_assert_equalfile(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_equalfile(argvars);
 }
 
-// "assert_notequal(expected, actual[, msg])" function
+/// "assert_notequal(expected, actual[, msg])" function
 static void f_assert_notequal(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_equal_common(argvars, ASSERT_NOTEQUAL);
@@ -536,15 +524,13 @@ static void f_assert_notmatch(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = assert_match_common(argvars, ASSERT_NOTMATCH);
 }
 
-// "assert_true(actual[, msg])" function
+/// "assert_true(actual[, msg])" function
 static void f_assert_true(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = assert_bool(argvars, true);
 }
 
-/*
- * "atan2()" function
- */
+/// "atan2()" function
 static void f_atan2(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   float_T fx;
@@ -558,27 +544,21 @@ static void f_atan2(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "browse(save, title, initdir, default)" function
- */
+/// "browse(save, title, initdir, default)" function
 static void f_browse(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_string = NULL;
   rettv->v_type = VAR_STRING;
 }
 
-/*
- * "browsedir(title, initdir)" function
- */
+/// "browsedir(title, initdir)" function
 static void f_browsedir(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   f_browse(argvars, rettv, NULL);
 }
 
 
-/*
- * Find a buffer by number or exact name.
- */
+/// Find a buffer by number or exact name.
 static buf_T *find_buffer(typval_T *avar)
 {
   buf_T *buf = NULL;
@@ -605,7 +585,7 @@ static buf_T *find_buffer(typval_T *avar)
   return buf;
 }
 
-// "bufadd(expr)" function
+/// "bufadd(expr)" function
 static void f_bufadd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *name = (char_u *)tv_get_string(&argvars[0]);
@@ -613,17 +593,13 @@ static void f_bufadd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = buflist_add(*name == NUL ? NULL : name, 0);
 }
 
-/*
- * "bufexists(expr)" function
- */
+/// "bufexists(expr)" function
 static void f_bufexists(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = (find_buffer(&argvars[0]) != NULL);
 }
 
-/*
- * "buflisted(expr)" function
- */
+/// "buflisted(expr)" function
 static void f_buflisted(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   buf_T *buf;
@@ -632,7 +608,7 @@ static void f_buflisted(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = (buf != NULL && buf->b_p_bl);
 }
 
-// "bufload(expr)" function
+/// "bufload(expr)" function
 static void f_bufload(typval_T *argvars, typval_T *unused, FunPtr fptr)
 {
   buf_T *buf = get_buf_arg(&argvars[0]);
@@ -647,9 +623,7 @@ static void f_bufload(typval_T *argvars, typval_T *unused, FunPtr fptr)
   }
 }
 
-/*
- * "bufloaded(expr)" function
- */
+/// "bufloaded(expr)" function
 static void f_bufloaded(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   buf_T *buf;
@@ -658,9 +632,7 @@ static void f_bufloaded(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = (buf != NULL && buf->b_ml.ml_mfp != NULL);
 }
 
-/*
- * "bufname(expr)" function
- */
+/// "bufname(expr)" function
 static void f_bufname(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const buf_T *buf;
@@ -676,9 +648,7 @@ static void f_bufname(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "bufnr(expr)" function
- */
+/// "bufnr(expr)" function
 static void f_bufnr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const buf_T *buf;
@@ -750,9 +720,7 @@ static void f_bufwinnr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   buf_win_common(argvars, rettv, true);
 }
 
-/*
- * Get buffer by number or pattern.
- */
+/// Get buffer by number or pattern.
 buf_T *tv_get_buf(typval_T *tv, int curtab_only)
 {
   char_u *name = tv->vval.v_string;
@@ -820,9 +788,7 @@ buf_T *get_buf_arg(typval_T *arg)
   return buf;
 }
 
-/*
- * "byte2line(byte)" function
- */
+/// "byte2line(byte)" function
 static void f_byte2line(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   long boff = tv_get_number(&argvars[0]) - 1;
@@ -857,17 +823,13 @@ static void byteidx(typval_T *argvars, typval_T *rettv, int comp)
   rettv->vval.v_number = (varnumber_T)(t - str);
 }
 
-/*
- * "byteidx()" function
- */
+/// "byteidx()" function
 static void f_byteidx(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   byteidx(argvars, rettv, FALSE);
 }
 
-/*
- * "byteidxcomp()" function
- */
+/// "byteidxcomp()" function
 static void f_byteidxcomp(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   byteidx(argvars, rettv, TRUE);
@@ -919,15 +881,13 @@ static void f_call(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "changenr()" function
- */
+/// "changenr()" function
 static void f_changenr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = curbuf->b_u_seq_cur;
 }
 
-// "chanclose(id[, stream])" function
+/// "chanclose(id[, stream])" function
 static void f_chanclose(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_NUMBER;
@@ -966,7 +926,7 @@ static void f_chanclose(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "chansend(id, data)" function
+/// "chansend(id, data)" function
 static void f_chansend(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_NUMBER;
@@ -1007,9 +967,7 @@ static void f_chansend(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "char2nr(string)" function
- */
+/// "char2nr(string)" function
 static void f_char2nr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if (argvars[1].v_type != VAR_UNKNOWN) {
@@ -1021,9 +979,10 @@ static void f_char2nr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = utf_ptr2char((const char_u *)tv_get_string(&argvars[0]));
 }
 
-/// Get the current cursor column and store it in 'rettv'. If 'charcol' is true,
-/// returns the character index of the column. Otherwise, returns the byte index
-/// of the column.
+/// Get the current cursor column and store it in 'rettv'.
+///
+/// @return  the character index of the column if 'charcol' is true,
+///          otherwise the byte index of the column.
 static void get_col(typval_T *argvars, typval_T *rettv, bool charcol)
 {
   colnr_T col = 0;
@@ -1064,7 +1023,7 @@ static void f_charcol(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   get_col(argvars, rettv, true);
 }
 
-// "charidx()" function
+/// "charidx()" function
 static void f_charidx(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = -1;
@@ -1110,7 +1069,7 @@ static void f_charidx(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = len > 0 ? len - 1 : 0;
 }
 
-// "chdir(dir)" function
+/// "chdir(dir)" function
 static void f_chdir(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *cwd;
@@ -1147,9 +1106,7 @@ static void f_chdir(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "cindent(lnum)" function
- */
+/// "cindent(lnum)" function
 static void f_cindent(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   pos_T pos;
@@ -1180,9 +1137,7 @@ static win_T *get_optional_window(typval_T *argvars, int idx)
   return win;
 }
 
-/*
- * "clearmatches()" function
- */
+/// "clearmatches()" function
 static void f_clearmatches(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   win_T *win = get_optional_window(argvars, 0);
@@ -1198,9 +1153,7 @@ static void f_col(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   get_col(argvars, rettv, false);
 }
 
-/*
- * "complete()" function
- */
+/// "complete()" function
 static void f_complete(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if ((State & INSERT) == 0) {
@@ -1227,17 +1180,13 @@ static void f_complete(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   set_completion(startcol - 1, argvars[1].vval.v_list);
 }
 
-/*
- * "complete_add()" function
- */
+/// "complete_add()" function
 static void f_complete_add(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = ins_compl_add_tv(&argvars[0], 0, false);
 }
 
-/*
- * "complete_check()" function
- */
+/// "complete_check()" function
 static void f_complete_check(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   int saved = RedrawingDisabled;
@@ -1248,7 +1197,7 @@ static void f_complete_check(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   RedrawingDisabled = saved;
 }
 
-// "complete_info()" function
+/// "complete_info()" function
 static void f_complete_info(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   tv_dict_alloc_ret(rettv);
@@ -1265,9 +1214,7 @@ static void f_complete_info(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   get_complete_info(what_list, rettv->vval.v_dict);
 }
 
-/*
- * "confirm(message, buttons[, default [, type]])" function
- */
+/// "confirm(message, buttons[, default [, type]])" function
 static void f_confirm(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char buf[NUMBUFLEN];
@@ -1322,17 +1269,13 @@ static void f_confirm(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "copy()" function
- */
+/// "copy()" function
 static void f_copy(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   var_item_copy(NULL, &argvars[0], rettv, false, 0);
 }
 
-/*
- * "count()" function
- */
+/// "count()" function
 static void f_count(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   long n = 0;
@@ -1423,11 +1366,9 @@ static void f_count(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = n;
 }
 
-/*
- * "cscope_connection([{num} , {dbpath} [, {prepend}]])" function
- *
- * Checks the existence of a cscope connection.
- */
+/// "cscope_connection([{num} , {dbpath} [, {prepend}]])" function
+///
+/// Checks the existence of a cscope connection.
 static void f_cscope_connection(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   int num = 0;
@@ -1622,13 +1563,14 @@ static void set_cursorpos(typval_T *argvars, typval_T *rettv, bool charcol)
 /// "cursor(list)"
 ///
 /// Moves the cursor to the specified line and column.
-/// Returns 0 when the position could be set, -1 otherwise.
+///
+/// @return  0 when the position could be set, -1 otherwise.
 static void f_cursor(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   set_cursorpos(argvars, rettv, false);
 }
 
-// "debugbreak()" function
+/// "debugbreak()" function
 static void f_debugbreak(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   int pid;
@@ -1652,7 +1594,7 @@ static void f_debugbreak(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "deepcopy()" function
+/// "deepcopy()" function
 static void f_deepcopy(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   int noref = 0;
@@ -1669,7 +1611,7 @@ static void f_deepcopy(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "delete()" function
+/// "delete()" function
 static void f_delete(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = -1;
@@ -1705,7 +1647,7 @@ static void f_delete(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// dictwatcheradd(dict, key, funcref) function
+/// dictwatcheradd(dict, key, funcref) function
 static void f_dictwatcheradd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if (check_secure()) {
@@ -1743,7 +1685,7 @@ static void f_dictwatcheradd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
                       callback);
 }
 
-// dictwatcherdel(dict, key, funcref) function
+/// dictwatcherdel(dict, key, funcref) function
 static void f_dictwatcherdel(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if (check_secure()) {
@@ -1852,25 +1794,19 @@ static void f_deletebufline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "did_filetype()" function
- */
+/// "did_filetype()" function
 static void f_did_filetype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = did_filetype;
 }
 
-/*
- * "diff_filler()" function
- */
+/// "diff_filler()" function
 static void f_diff_filler(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = MAX(0, diff_check(curwin, tv_get_lnum(argvars)));
 }
 
-/*
- * "diff_hlID()" function
- */
+/// "diff_hlID()" function
 static void f_diff_hlID(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   linenr_T lnum = tv_get_lnum(argvars);
@@ -1922,9 +1858,7 @@ static void f_diff_hlID(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = hlID == (hlf_T)0 ? 0 : (int)(hlID + 1);
 }
 
-/*
- * "empty({expr})" function
- */
+/// "empty({expr})" function
 static void f_empty(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   bool n = true;
@@ -2021,9 +1955,7 @@ static void f_environ(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   os_free_fullenv(env);
 }
 
-/*
- * "escape({string}, {chars})" function
- */
+/// "escape({string}, {chars})" function
 static void f_escape(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char buf[NUMBUFLEN];
@@ -2047,9 +1979,7 @@ static void f_getenv(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->v_type = VAR_STRING;
 }
 
-/*
- * "eval()" function
- */
+/// "eval()" function
 static void f_eval(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *s = tv_get_string_chk(&argvars[0]);
@@ -2070,17 +2000,13 @@ static void f_eval(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "eventhandler()" function
- */
+/// "eventhandler()" function
 static void f_eventhandler(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = vgetc_busy;
 }
 
-/*
- * "executable()" function
- */
+/// "executable()" function
 static void f_executable(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   if (tv_check_for_string(&argvars[0]) == FAIL) {
@@ -2188,13 +2114,13 @@ static void execute_common(typval_T *argvars, typval_T *rettv, FunPtr fptr, int
   capture_ga = save_capture_ga;
 }
 
-// "execute(command)" function
+/// "execute(command)" function
 static void f_execute(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   execute_common(argvars, rettv, fptr, 0);
 }
 
-// "win_execute(win_id, command)" function
+/// "win_execute(win_id, command)" function
 static void f_win_execute(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   // Return an empty string if something fails.
@@ -2224,9 +2150,7 @@ static void f_exepath(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_string = (char_u *)path;
 }
 
-/*
- * "exists()" function
- */
+/// "exists()" function
 static void f_exists(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   int n = false;
@@ -2266,9 +2190,7 @@ static void f_exists(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = n;
 }
 
-/*
- * "expand()" function
- */
+/// "expand()" function
 static void f_expand(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   size_t len;
@@ -2353,8 +2275,8 @@ static void f_menu_get(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   menu_get((char_u *)tv_get_string(&argvars[0]), modes, rettv->vval.v_list);
 }
 
-// "expandcmd()" function
-// Expand all the special characters in a command string.
+/// "expandcmd()" function
+/// Expand all the special characters in a command string.
 static void f_expandcmd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char *errormsg = NULL;
@@ -2414,10 +2336,8 @@ static void f_flatten(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "extend(list, list [, idx])" function
- * "extend(dict, dict [, action])" function
- */
+/// "extend(list, list [, idx])" function
+/// "extend(dict, dict [, action])" function
 static void f_extend(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *const arg_errmsg = N_("extend() argument");
@@ -2494,9 +2414,7 @@ static void f_extend(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "feedkeys()" function
- */
+/// "feedkeys()" function
 static void f_feedkeys(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   // This is not allowed in the sandbox.  If the commands would still be
@@ -2525,10 +2443,9 @@ static void f_filereadable(typval_T *argvars, typval_T *rettv, FunPtr fptr)
     (*p && !os_isdir((const char_u *)p) && os_file_is_readable(p));
 }
 
-/*
- * Return 0 for not writable, 1 for writable file, 2 for a dir which we have
- * rights to write into.
- */
+/// @return  0 for not writable
+///          1 for writable file
+///          2 for a dir which we have rights to write into.
 static void f_filewritable(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *filename = tv_get_string(&argvars[0]);
@@ -2595,33 +2512,25 @@ static void findfilendir(typval_T *argvars, typval_T *rettv, int find_what)
 }
 
 
-/*
- * "filter()" function
- */
+/// "filter()" function
 static void f_filter(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   filter_map(argvars, rettv, FALSE);
 }
 
-/*
- * "finddir({fname}[, {path}[, {count}]])" function
- */
+/// "finddir({fname}[, {path}[, {count}]])" function
 static void f_finddir(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   findfilendir(argvars, rettv, FINDFILE_DIR);
 }
 
-/*
- * "findfile({fname}[, {path}[, {count}]])" function
- */
+/// "findfile({fname}[, {path}[, {count}]])" function
 static void f_findfile(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   findfilendir(argvars, rettv, FINDFILE_FILE);
 }
 
-/*
- * "float2nr({float})" function
- */
+/// "float2nr({float})" function
 static void f_float2nr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   float_T f;
@@ -2637,9 +2546,7 @@ static void f_float2nr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "fmod()" function
- */
+/// "fmod()" function
 static void f_fmod(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   float_T fx;
@@ -2653,18 +2560,14 @@ static void f_fmod(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "fnameescape({string})" function
- */
+/// "fnameescape({string})" function
 static void f_fnameescape(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_string = (char_u *)vim_strsave_fnameescape(tv_get_string(&argvars[0]), false);
   rettv->v_type = VAR_STRING;
 }
 
-/*
- * "fnamemodify({fname}, {mods})" function
- */
+/// "fnamemodify({fname}, {mods})" function
 static void f_fnamemodify(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *fbuf = NULL;
@@ -2693,9 +2596,7 @@ static void f_fnamemodify(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 }
 
 
-/*
- * "foldclosed()" function
- */
+/// "foldclosed()" function
 static void foldclosed_both(typval_T *argvars, typval_T *rettv, int end)
 {
   const linenr_T lnum = tv_get_lnum(argvars);
@@ -2714,25 +2615,19 @@ static void foldclosed_both(typval_T *argvars, typval_T *rettv, int end)
   rettv->vval.v_number = -1;
 }
 
-/*
- * "foldclosed()" function
- */
+/// "foldclosed()" function
 static void f_foldclosed(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   foldclosed_both(argvars, rettv, FALSE);
 }
 
-/*
- * "foldclosedend()" function
- */
+/// "foldclosedend()" function
 static void f_foldclosedend(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   foldclosed_both(argvars, rettv, TRUE);
 }
 
-/*
- * "foldlevel()" function
- */
+/// "foldlevel()" function
 static void f_foldlevel(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const linenr_T lnum = tv_get_lnum(argvars);
@@ -2741,9 +2636,7 @@ static void f_foldlevel(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "foldtext()" function
- */
+/// "foldtext()" function
 static void f_foldtext(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   linenr_T foldstart;
@@ -2796,9 +2689,7 @@ static void f_foldtext(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "foldtextresult(lnum)" function
- */
+/// "foldtextresult(lnum)" function
 static void f_foldtextresult(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *text;
@@ -2829,9 +2720,7 @@ static void f_foldtextresult(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   entered = false;
 }
 
-/*
- * "foreground()" function
- */
+/// "foreground()" function
 static void f_foreground(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
 }
@@ -2858,9 +2747,7 @@ static void f_garbagecollect(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "get()" function
- */
+/// "get()" function
 static void f_get(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   listitem_T *li;
@@ -3020,12 +2907,12 @@ static void f_getbufinfo(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * Get line or list of lines from buffer "buf" into "rettv".
- * Return a range (from start to end) of lines in rettv from the specified
- * buffer.
- * If 'retlist' is TRUE, then the lines are returned as a Vim List.
- */
+/// Get line or list of lines from buffer "buf" into "rettv".
+///
+/// @param retlist  if TRUE, then the lines are returned as a Vim List.
+///
+/// @return  range (from start to end) of lines in rettv from the specified
+///          buffer.
 static void get_buffer_lines(buf_T *buf, linenr_T start, linenr_T end, int retlist, typval_T *rettv)
 {
   rettv->v_type = (retlist ? VAR_LIST : VAR_STRING);
@@ -3058,9 +2945,7 @@ static void get_buffer_lines(buf_T *buf, linenr_T start, linenr_T end, int retli
   }
 }
 
-/*
- * "getbufline()" function
- */
+/// "getbufline()" function
 static void f_getbufline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   buf_T *const buf = tv_get_buf_from_arg(&argvars[0]);
@@ -3073,9 +2958,7 @@ static void f_getbufline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   get_buffer_lines(buf, lnum, end, true, rettv);
 }
 
-/*
- * "getbufvar()" function
- */
+/// "getbufvar()" function
 static void f_getbufvar(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   bool done = false;
@@ -3135,7 +3018,7 @@ f_getbufvar_end:
   }
 }
 
-// "getchangelist()" function
+/// "getchangelist()" function
 static void f_getchangelist(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   tv_list_alloc_ret(rettv, 2);
@@ -3175,7 +3058,7 @@ static void f_getchangelist(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "getchar()" and "getcharstr()" functions
+/// "getchar()" and "getcharstr()" functions
 static void getchar_common(typval_T *argvars, typval_T *rettv)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -3277,13 +3160,13 @@ static void getchar_common(typval_T *argvars, typval_T *rettv)
   }
 }
 
-// "getchar()" function
+/// "getchar()" function
 static void f_getchar(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   getchar_common(argvars, rettv);
 }
 
-// "getcharstr()" function
+/// "getcharstr()" function
 static void f_getcharstr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   getchar_common(argvars, rettv);
@@ -3303,9 +3186,7 @@ static void f_getcharstr(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "getcharmod()" function
- */
+/// "getcharmod()" function
 static void f_getcharmod(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = mod_mask;
@@ -3372,9 +3253,7 @@ static void f_getcharpos(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   getpos_both(argvars, rettv, false, true);
 }
 
-/*
- * "getcharsearch()" function
- */
+/// "getcharsearch()" function
 static void f_getcharsearch(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   tv_dict_alloc_ret(rettv);
@@ -3386,26 +3265,20 @@ static void f_getcharsearch(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   tv_dict_add_nr(dict, S_LEN("until"), last_csearch_until());
 }
 
-/*
- * "getcmdline()" function
- */
+/// "getcmdline()" function
 static void f_getcmdline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_STRING;
   rettv->vval.v_string = get_cmdline_str();
 }
 
-/*
- * "getcmdpos()" function
- */
+/// "getcmdpos()" function
 static void f_getcmdpos(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->vval.v_number = get_cmdline_pos() + 1;
 }
 
-/*
- * "getcmdtype()" function
- */
+/// "getcmdtype()" function
 static void f_getcmdtype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_STRING;
@@ -3413,9 +3286,7 @@ static void f_getcmdtype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_string[0] = get_cmdline_type();
 }
 
-/*
- * "getcmdwintype()" function
- */
+/// "getcmdwintype()" function
 static void f_getcmdwintype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_STRING;
@@ -3424,7 +3295,7 @@ static void f_getcmdwintype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_string[0] = cmdwin_type;
 }
 
-// "getcompletion()" function
+/// "getcompletion()" function
 static void f_getcompletion(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *pat;
@@ -3623,18 +3494,14 @@ static void f_getcwd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   xfree(cwd);
 }
 
-/*
- * "getfontname()" function
- */
+/// "getfontname()" function
 static void f_getfontname(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   rettv->v_type = VAR_STRING;
   rettv->vval.v_string = NULL;
 }
 
-/*
- * "getfperm({fname})" function
- */
+/// "getfperm({fname})" function
 static void f_getfperm(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char *perm = NULL;
@@ -3654,9 +3521,7 @@ static void f_getfperm(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_string = (char_u *)perm;
 }
 
-/*
- * "getfsize({fname})" function
- */
+/// "getfsize({fname})" function
 static void f_getfsize(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *fname = tv_get_string(&argvars[0]);
@@ -3681,9 +3546,7 @@ static void f_getfsize(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "getftime({fname})" function
- */
+/// "getftime({fname})" function
 static void f_getftime(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *fname = tv_get_string(&argvars[0]);
@@ -3696,9 +3559,7 @@ static void f_getftime(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "getftype({fname})" function
- */
+/// "getftype({fname})" function
 static void f_getftype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   char_u *type = NULL;
@@ -3732,7 +3593,7 @@ static void f_getftype(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_string = type;
 }
 
-// "getjumplist()" function
+/// "getjumplist()" function
 static void f_getjumplist(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   tv_list_alloc_ret(rettv, kListLenMayKnow);
@@ -3763,9 +3624,7 @@ static void f_getjumplist(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-/*
- * "getline(lnum, [end])" function
- */
+/// "getline(lnum, [end])" function
 static void f_getline(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   linenr_T end;
@@ -3809,9 +3668,7 @@ static void f_getmarklist(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   get_buf_local_marks(buf, rettv->vval.v_list);
 }
 
-/*
- * "getmatches()" function
- */
+/// "getmatches()" function
 static void f_getmatches(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   matchitem_T *cur;
@@ -3866,7 +3723,7 @@ static void f_getmatches(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
-// "getmousepos()" function
+/// "getmousepos()" function
 static void f_getmousepos(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   dict_T *d;
@@ -3919,9 +3776,7 @@ static void f_getmousepos(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   tv_dict_add_nr(d, S_LEN("column"), column);<