refactor: convert function comments to doxygen format (#17710)

src/nvim/eval/userfunc.c

@@ -201,7 +201,7 @@ static void register_closure(ufunc_T *fp)
 }
 
 
-/// Get a name for a lambda.  Returned in static memory.
+/// @return  a name for a lambda.  Returned in static memory.
 char_u *get_lambda_name(void)
 {
   static char_u name[30];
@@ -544,7 +544,8 @@ static char_u *fname_trans_sid(const char_u *const name, char_u *const fname_buf
 }
 
 /// Find a function by name, return pointer to it in ufuncs.
-/// @return NULL for unknown function.
+///
+/// @return  NULL for unknown function.
 ufunc_T *find_func(const char_u *name)
 {
   hashitem_T *hi;
@@ -556,11 +557,9 @@ ufunc_T *find_func(const char_u *name)
   return NULL;
 }
 
-/*
+/// Copy the function name of "fp" to buffer "buf".
- * Copy the function name of "fp" to buffer "buf".
+/// "buf" must be able to hold the function name plus three bytes.
- * "buf" must be able to hold the function name plus three bytes.
+/// Takes care of script-local function names.
- * Takes care of script-local function names.
- */
 static void cat_func_name(char_u *buf, ufunc_T *fp)
 {
   if (fp->uf_name[0] == K_SPECIAL) {
@@ -571,9 +570,7 @@ static void cat_func_name(char_u *buf, ufunc_T *fp)
   }
 }
 
-/*
+/// Add a number variable "name" to dict "dp" with value "nr".
- * Add a number variable "name" to dict "dp" with value "nr".
- */
 static void add_nr_var(dict_T *dp, dictitem_T *v, char *name, varnumber_T nr)
 {
 #ifndef __clang_analyzer__
@@ -586,7 +583,7 @@ static void add_nr_var(dict_T *dp, dictitem_T *v, char *name, varnumber_T nr)
   v->di_tv.vval.v_number = nr;
 }
 
-// Free "fc"
+/// Free "fc"
 static void free_funccal(funccall_T *fc)
 {
   for (int i = 0; i < fc->fc_funcs.ga_len; i++) {
@@ -606,9 +603,9 @@ static void free_funccal(funccall_T *fc)
   xfree(fc);
 }
 
-// Free "fc" and what it contains.
+/// Free "fc" and what it contains.
-// Can be called only when "fc" is kept beyond the period of it called,
+/// Can be called only when "fc" is kept beyond the period of it called,
-// i.e. after cleanup_function_call(fc).
+/// i.e. after cleanup_function_call(fc).
 static void free_funccal_contents(funccall_T *fc)
 {
   // Free all l: variables.
@@ -757,7 +754,7 @@ static void func_clear_items(ufunc_T *fp)
 /// Free all things that a function contains. Does not free the function
 /// itself, use func_free() for that.
 ///
-/// param[in]        force        When true, we are exiting.
+/// @param[in] force  When true, we are exiting.
 static void func_clear(ufunc_T *fp, bool force)
 {
   if (fp->uf_cleared) {
@@ -773,7 +770,7 @@ static void func_clear(ufunc_T *fp, bool force)
 /// Free a function and remove it from the list of functions. Does not free
 /// what a function contains, call func_clear() first.
 ///
-/// param[in]        fp        The function to free.
+/// @param[in] fp  The function to free.
 static void func_free(ufunc_T *fp)
 {
   // only remove it when not done already, otherwise we would remove a newer
@@ -786,7 +783,7 @@ static void func_free(ufunc_T *fp)
 
 /// Free all things that a function contains and free the function itself.
 ///
-/// param[in]        force        When true, we are exiting.
+/// @param[in] force  When true, we are exiting.
 static void func_clear_free(ufunc_T *fp, bool force)
 {
   func_clear(fp, force);
@@ -795,13 +792,13 @@ static void func_clear_free(ufunc_T *fp, bool force)
 
 /// Call a user function
 ///
-/// @param  fp  Function to call.
+/// @param fp  Function to call.
-/// @param[in]  argcount  Number of arguments.
+/// @param[in] argcount  Number of arguments.
-/// @param  argvars  Arguments.
+/// @param argvars  Arguments.
-/// @param[out]  rettv  Return value.
+/// @param[out] rettv  Return value.
-/// @param[in]  firstline  First line of range.
+/// @param[in] firstline  First line of range.
-/// @param[in]  lastline  Last line of range.
+/// @param[in] lastline  Last line of range.
-/// @param  selfdict  Dictionary for "self" for dictionary functions.
+/// @param selfdict  Dictionary for "self" for dictionary functions.
 void call_user_func(ufunc_T *fp, int argcount, typval_T *argvars, typval_T *rettv,
                     linenr_T firstline, linenr_T lastline, dict_T *selfdict)
   FUNC_ATTR_NONNULL_ARG(1, 3, 4)
@@ -1230,8 +1227,8 @@ static bool func_name_refcount(char_u *name)
 
 static funccal_entry_T *funccal_stack = NULL;
 
-// Save the current function call pointer, and set it to NULL.
+/// Save the current function call pointer, and set it to NULL.
-// Used when executing autocommands and for ":source".
+/// Used when executing autocommands and for ":source".
 void save_funccal(funccal_entry_T *entry)
 {
   entry->top_funccal = current_funccal;
@@ -1384,8 +1381,8 @@ func_call_skip_call:
   return r;
 }
 
-// Give an error message for the result of a function.
+/// Give an error message for the result of a function.
-// Nothing if "error" is FCERR_NONE.
+/// Nothing if "error" is FCERR_NONE.
 static void user_func_error(int error, const char_u *name)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -1902,9 +1899,7 @@ theend:
   return name;
 }
 
-/*
+/// ":function"
- * ":function"
- */
 void ex_function(exarg_T *eap)
 {
   char_u *theline;
@@ -2595,11 +2590,9 @@ ret_free:
   }
 }  // NOLINT(readability/fn_size)
 
-/*
+/// @return  5 if "p" starts with "<SID>" or "<SNR>" (ignoring case).
- * Return 5 if "p" starts with "<SID>" or "<SNR>" (ignoring case).
+///          2 if "p" starts with "s:".
- * Return 2 if "p" starts with "s:".
+///          0 otherwise.
- * Return 0 otherwise.
- */
 int eval_fname_script(const char *const p)
 {
   // Use mb_strnicmp() because in Turkish comparing the "I" may not work with
@@ -2625,10 +2618,10 @@ bool translated_function_exists(const char *name)
 
 /// Check whether function with the given name exists
 ///
-/// @param[in]  name  Function name.
+/// @param[in] name  Function name.
-/// @param[in]  no_deref  Whether to dereference a Funcref.
+/// @param[in] no_deref  Whether to dereference a Funcref.
 ///
-/// @return True if it exists, false otherwise.
+/// @return  true if it exists, false otherwise.
 bool function_exists(const char *const name, bool no_deref)
 {
   const char_u *nm = (const char_u *)name;
@@ -2651,10 +2644,8 @@ bool function_exists(const char *const name, bool no_deref)
   return n;
 }
 
-/*
+/// Function given to ExpandGeneric() to obtain the list of user defined
- * Function given to ExpandGeneric() to obtain the list of user defined
+/// function names.
- * function names.
- */
 char_u *get_user_func_name(expand_T *xp, int idx)
 {
   static size_t done;
@@ -2771,10 +2762,8 @@ void ex_delfunction(exarg_T *eap)
   }
 }
 
-/*
+/// Unreference a Function: decrement the reference count and free it when it
- * Unreference a Function: decrement the reference count and free it when it
+/// becomes zero.
- * becomes zero.
- */
 void func_unref(char_u *name)
 {
   ufunc_T *fp = NULL;
@@ -2868,9 +2857,7 @@ static int can_free_funccal(funccall_T *fc, int copyID)
          && fc->fc_copyID != copyID;
 }
 
-/*
+/// ":return [expr]"
- * ":return [expr]"
- */
 void ex_return(exarg_T *eap)
 {
   char_u *arg = eap->arg;
@@ -2921,9 +2908,7 @@ void ex_return(exarg_T *eap)
 
 // TODO(ZyX-I): move to eval/ex_cmds
 
-/*
+/// ":1,25call func(arg1, arg2)" function call.
- * ":1,25call func(arg1, arg2)" function call.
- */
 void ex_call(exarg_T *eap)
 {
   char_u *arg = eap->arg;
@@ -3050,14 +3035,16 @@ end:
   xfree(tofree);
 }
 
-/*
+/// Return from a function.  Possibly makes the return pending.  Also called
- * Return from a function.  Possibly makes the return pending.  Also called
+/// for a pending return at the ":endtry" or after returning from an extra
- * for a pending return at the ":endtry" or after returning from an extra
+/// do_cmdline().  "reanimate" is used in the latter case.
- * do_cmdline().  "reanimate" is used in the latter case.  "is_cmd" is set
+///
- * when called due to a ":return" command.  "rettv" may point to a typval_T
+/// @param reanimate  used after returning from an extra do_cmdline().
- * with the return rettv.  Returns TRUE when the return can be carried out,
+/// @param is_cmd     set when called due to a ":return" command.
- * FALSE when the return gets pending.
+/// @param rettv      may point to a typval_T with the return rettv.
- */
+///
+/// @return  TRUE when the return can be carried out,
+///          FALSE when the return gets pending.
 int do_return(exarg_T *eap, int reanimate, int is_cmd, void *rettv)
 {
   int idx;
@@ -3068,12 +3055,10 @@ int do_return(exarg_T *eap, int reanimate, int is_cmd, void *rettv)
     current_funccal->returned = false;
   }
 
-  //
   // Cleanup (and deactivate) conditionals, but stop when a try conditional
   // not in its finally clause (which then is to be executed next) is found.
   // In this case, make the ":return" pending for execution at the ":endtry".
   // Otherwise, return normally.
-  //
   idx = cleanup_conditionals(eap->cstack, 0, true);
   if (idx >= 0) {
     cstack->cs_pending[idx] = CSTP_RETURN;
@@ -3126,10 +3111,8 @@ int do_return(exarg_T *eap, int reanimate, int is_cmd, void *rettv)
   return idx < 0;
 }
 
-/*
+/// Generate a return command for producing the value of "rettv".  The result
- * Generate a return command for producing the value of "rettv".  The result
+/// is an allocated string.  Used by report_pending() for verbose messages.
- * is an allocated string.  Used by report_pending() for verbose messages.
- */
 char_u *get_return_cmd(void *rettv)
 {
   char_u *s = NULL;
@@ -3151,11 +3134,10 @@ char_u *get_return_cmd(void *rettv)
   return vim_strsave(IObuff);
 }
 
-/*
+/// Get next function line.
- * Get next function line.
+/// Called by do_cmdline() to get the next line.
- * Called by do_cmdline() to get the next line.
+///
- * Returns allocated string, or NULL for end of function.
+/// @return  allocated string, or NULL for end of function.
- */
 char_u *get_func_line(int c, void *cookie, int indent, bool do_concat)
 {
   funccall_T *fcp = (funccall_T *)cookie;
@@ -3206,10 +3188,8 @@ char_u *get_func_line(int c, void *cookie, int indent, bool do_concat)
   return retval;
 }
 
-/*
+/// @return  TRUE if the currently active function should be ended, because a
- * Return TRUE if the currently active function should be ended, because a
+///          return was encountered or an error occurred.  Used inside a ":while".
- * return was encountered or an error occurred.  Used inside a ":while".
- */
 int func_has_ended(void *cookie)
 {
   funccall_T *fcp = (funccall_T *)cookie;
@@ -3220,9 +3200,7 @@ int func_has_ended(void *cookie)
          || fcp->returned;
 }
 
-/*
+/// @return  TRUE if cookie indicates a function which "abort"s on errors.
- * return TRUE if cookie indicates a function which "abort"s on errors.
- */
 int func_has_abort(void *cookie)
 {
   return ((funccall_T *)cookie)->func->uf_flags & FC_ABORT;
@@ -3289,41 +3267,31 @@ void make_partial(dict_T *const selfdict, typval_T *const rettv)
   }
 }
 
-/*
+/// @return  the name of the executed function.
- * Return the name of the executed function.
- */
 char_u *func_name(void *cookie)
 {
   return ((funccall_T *)cookie)->func->uf_name;
 }
 
-/*
+/// @return  the address holding the next breakpoint line for a funccall cookie.
- * Return the address holding the next breakpoint line for a funccall cookie.
- */
 linenr_T *func_breakpoint(void *cookie)
 {
   return &((funccall_T *)cookie)->breakpoint;
 }
 
-/*
+/// @return  the address holding the debug tick for a funccall cookie.
- * Return the address holding the debug tick for a funccall cookie.
- */
 int *func_dbg_tick(void *cookie)
 {
   return &((funccall_T *)cookie)->dbg_tick;
 }
 
-/*
+/// @return  the nesting level for a funccall cookie.
- * Return the nesting level for a funccall cookie.
- */
 int func_level(void *cookie)
 {
   return ((funccall_T *)cookie)->level;
 }
 
-/*
+/// @return  TRUE when a function was ended by a ":return" command.
- * Return TRUE when a function was ended by a ":return" command.
- */
 int current_func_returned(void)
 {
   return current_funccal->returned;
@@ -3372,8 +3340,8 @@ funccall_T *get_funccal(void)
   return funccal;
 }
 
-/// Return the hashtable used for local variables in the current funccal.
+/// @return  hashtable used for local variables in the current funccal or
-/// Return NULL if there is no current funccal.
+///          NULL if there is no current funccal.
 hashtab_T *get_funccal_local_ht(void)
 {
   if (current_funccal == NULL) {
@@ -3382,8 +3350,8 @@ hashtab_T *get_funccal_local_ht(void)
   return &get_funccal()->l_vars.dv_hashtab;
 }
 
-/// Return the l: scope variable.
+/// @return   the l: scope variable or
-/// Return NULL if there is no current funccal.
+///           NULL if there is no current funccal.
 dictitem_T *get_funccal_local_var(void)
 {
   if (current_funccal == NULL) {
@@ -3392,8 +3360,8 @@ dictitem_T *get_funccal_local_var(void)
   return (dictitem_T *)&get_funccal()->l_vars_var;
 }
 
-/// Return the hashtable used for argument in the current funccal.
+/// @return  the hashtable used for argument in the current funccal or
-/// Return NULL if there is no current funccal.
+///          NULL if there is no current funccal.
 hashtab_T *get_funccal_args_ht(void)
 {
   if (current_funccal == NULL) {
@@ -3402,8 +3370,8 @@ hashtab_T *get_funccal_args_ht(void)
   return &get_funccal()->l_avars.dv_hashtab;
 }
 
-/// Return the a: scope variable.
+/// @return  the a: scope variable or
-/// Return NULL if there is no current funccal.
+///          NULL if there is no current funccal.
 dictitem_T *get_funccal_args_var(void)
 {
   if (current_funccal == NULL) {
@@ -3412,9 +3380,7 @@ dictitem_T *get_funccal_args_var(void)
   return (dictitem_T *)&current_funccal->l_avars_var;
 }
 
-/*
+/// List function variables, if there is a function.
- * List function variables, if there is a function.
- */
 void list_func_vars(int *first)
 {
   if (current_funccal != NULL) {
@@ -3423,9 +3389,8 @@ void list_func_vars(int *first)
   }
 }
 
-/// If "ht" is the hashtable for local variables in the current funccal, return
+/// @return  if "ht" is the hashtable for local variables in the current
-/// the dict that contains it.
+///          funccal, return the dict that contains it. Otherwise return NULL.
-/// Otherwise return NULL.
 dict_T *get_current_funccal_dict(hashtab_T *ht)
 {
   if (current_funccal != NULL && ht == &current_funccal->l_vars.dv_hashtab) {
@@ -3589,7 +3554,7 @@ bool set_ref_in_func_args(int copyID)
 /// "list_stack" is used to add lists to be marked.  Can be NULL.
 /// "ht_stack" is used to add hashtabs to be marked.  Can be NULL.
 ///
-/// @return true if setting references failed somehow.
+/// @return  true if setting references failed somehow.
 bool set_ref_in_func(char_u *name, ufunc_T *fp_in, int copyID)
 {
   ufunc_T *fp = fp_in;

src/nvim/event/process.c

@@ -237,7 +237,7 @@ void process_stop(Process *proc) FUNC_ATTR_NONNULL_ALL
                  KILL_TIMEOUT_MS, 0);
 }
 
-// Frees process-owned resources.
+/// Frees process-owned resources.
 void process_free(Process *proc) FUNC_ATTR_NONNULL_ALL
 {
   if (proc->argv != NULL) {

src/nvim/event/rstream.c

@@ -85,7 +85,7 @@ static void on_rbuffer_nonfull(RBuffer *buf, void *data)
 
 // Callbacks used by libuv
 
-// Called by libuv to allocate memory for reading.
+/// Called by libuv to allocate memory for reading.
 static void alloc_cb(uv_handle_t *handle, size_t suggested, uv_buf_t *buf)
 {
   Stream *stream = handle->data;
@@ -95,9 +95,9 @@ static void alloc_cb(uv_handle_t *handle, size_t suggested, uv_buf_t *buf)
   buf->len = UV_BUF_LEN(write_count);
 }
 
-// Callback invoked by libuv after it copies the data into the buffer provided
+/// Callback invoked by libuv after it copies the data into the buffer provided
-// by `alloc_cb`. This is also called on EOF or when `alloc_cb` returns a
+/// by `alloc_cb`. This is also called on EOF or when `alloc_cb` returns a
-// 0-length buffer.
+/// 0-length buffer.
 static void read_cb(uv_stream_t *uvstream, ssize_t cnt, const uv_buf_t *buf)
 {
   Stream *stream = uvstream->data;
@@ -134,11 +134,11 @@ static void read_cb(uv_stream_t *uvstream, ssize_t cnt, const uv_buf_t *buf)
   invoke_read_cb(stream, nread, false);
 }
 
-// Called by the by the 'idle' handle to emulate a reading event
+/// Called by the by the 'idle' handle to emulate a reading event
-//
+///
-// Idle callbacks are invoked once per event loop:
+/// Idle callbacks are invoked once per event loop:
-//  - to perform some very low priority activity.
+///  - to perform some very low priority activity.
-//  - to keep the loop "alive" (so there is always an event to process)
+///  - to keep the loop "alive" (so there is always an event to process)
 static void fread_idle_cb(uv_idle_t *handle)
 {
   uv_fs_t req;

src/nvim/ex_session.c

@@ -98,10 +98,11 @@ static int ses_winsizes(FILE *fd, int restore_size, win_T *tab_firstwin)
   return OK;
 }
 
-// Write commands to "fd" to recursively create windows for frame "fr",
+/// Write commands to "fd" to recursively create windows for frame "fr",
-// horizontally and vertically split.
+/// horizontally and vertically split.
-// After the commands the last window in the frame is the current window.
+/// After the commands the last window in the frame is the current window.
-// Returns FAIL when writing the commands to "fd" fails.
+///
+/// @return  FAIL when writing the commands to "fd" fails.
 static int ses_win_rec(FILE *fd, frame_T *fr)
 {
   frame_T *frc;
@@ -144,8 +145,9 @@ static int ses_win_rec(FILE *fd, frame_T *fr)
   return OK;
 }
 
-// Skip frames that don't contain windows we want to save in the Session.
+/// Skip frames that don't contain windows we want to save in the Session.
-// Returns NULL when there none.
+///
+/// @return  NULL when there none.
 static frame_T *ses_skipframe(frame_T *fr)
 {
   frame_T *frc;
@@ -158,8 +160,8 @@ static frame_T *ses_skipframe(frame_T *fr)
   return frc;
 }
 
-// Return true if frame "fr" has a window somewhere that we want to save in
+/// @return  true if frame "fr" has a window somewhere that we want to save in
-// the Session.
+///          the Session.
 static bool ses_do_frame(const frame_T *fr)
   FUNC_ATTR_NONNULL_ARG(1)
 {
@@ -176,7 +178,7 @@ static bool ses_do_frame(const frame_T *fr)
   return false;
 }
 
-/// Return non-zero if window "wp" is to be stored in the Session.
+/// @return  non-zero if window "wp" is to be stored in the Session.
 static int ses_do_win(win_T *wp)
 {
   if (wp->w_buffer->b_fname == NULL
@@ -229,7 +231,7 @@ static int ses_arglist(FILE *fd, char *cmd, garray_T *gap, int fullname, unsigne
   return OK;
 }
 
-/// Gets the buffer name for `buf`.
+/// @return  the buffer name for `buf`.
 static char *ses_get_fname(buf_T *buf, unsigned *flagp)
 {
   // Use the short file name if the current directory is known at the time
@@ -249,7 +251,8 @@ static char *ses_get_fname(buf_T *buf, unsigned *flagp)
 
 /// Write a buffer name to the session file.
 /// Also ends the line, if "add_eol" is true.
-/// Returns FAIL if writing fails.
+///
+/// @return  FAIL if writing fails.
 static int ses_fname(FILE *fd, buf_T *buf, unsigned *flagp, bool add_eol)
 {
   char *name = ses_get_fname(buf, flagp);
@@ -260,11 +263,11 @@ static int ses_fname(FILE *fd, buf_T *buf, unsigned *flagp, bool add_eol)
   return OK;
 }
 
-// Escapes a filename for session writing.
+/// Escapes a filename for session writing.
-// Takes care of "slash" flag in 'sessionoptions' and escapes special
+/// Takes care of "slash" flag in 'sessionoptions' and escapes special
-// characters.
+/// characters.
-//
+///
-// Returns allocated string or NULL.
+/// @return  allocated string or NULL.
 static char *ses_escape_fname(char *name, unsigned *flagp)
 {
   char *p;
@@ -283,10 +286,11 @@ static char *ses_escape_fname(char *name, unsigned *flagp)
   return p;
 }
 
-// Write a file name to the session file.
+/// Write a file name to the session file.
-// Takes care of the "slash" option in 'sessionoptions' and escapes special
+/// Takes care of the "slash" option in 'sessionoptions' and escapes special
-// characters.
+/// characters.
-// Returns FAIL if writing fails.
+///
+/// @return  FAIL if writing fails.
 static int ses_put_fname(FILE *fd, char_u *name, unsigned *flagp)
 {
   char *p = ses_escape_fname((char *)name, flagp);
@@ -1052,7 +1056,7 @@ void ex_mkrc(exarg_T *eap)
   xfree(viewFile);
 }
 
-/// Get the name of the view file for the current buffer.
+/// @return  the name of the view file for the current buffer.
 static char *get_view_file(int c)
 {
   if (curbuf->b_ffname == NULL) {
@@ -1100,7 +1104,7 @@ static char *get_view_file(int c)
   return retval;
 }
 
-// TODO(justinmk): remove this, not needed after 5ba3cecb68cd.
+/// TODO(justinmk): remove this, not needed after 5ba3cecb68cd.
 int put_eol(FILE *fd)
 {
   if (putc('\n', fd) < 0) {
@@ -1109,7 +1113,7 @@ int put_eol(FILE *fd)
   return OK;
 }
 
-// TODO(justinmk): remove this, not needed after 5ba3cecb68cd.
+/// TODO(justinmk): remove this, not needed after 5ba3cecb68cd.
 int put_line(FILE *fd, char *s)
 {
   if (fprintf(fd, "%s\n", s) < 0) {

src/nvim/extmark.c

@@ -175,8 +175,9 @@ static bool extmark_setraw(buf_T *buf, uint64_t mark, int row, colnr_T col)
   return true;
 }
 
-// Remove an extmark
+/// Remove an extmark
-// Returns 0 on missing id
+///
+/// @return  0 on missing id
 bool extmark_del(buf_T *buf, uint32_t ns_id, uint32_t id)
 {
   MarkTreeIter itr[1] = { 0 };
@@ -203,8 +204,8 @@ bool extmark_del(buf_T *buf, uint32_t ns_id, uint32_t id)
   return true;
 }
 
-// Free extmarks in a ns between lines
+/// Free extmarks in a ns between lines
-// if ns = 0, it means clear all namespaces
+/// if ns = 0, it means clear all namespaces
 bool extmark_clear(buf_T *buf, uint32_t ns_id, int l_row, colnr_T l_col, int u_row, colnr_T u_col)
 {
   if (!map_size(buf->b_extmark_ns)) {
@@ -287,12 +288,13 @@ bool extmark_clear(buf_T *buf, uint32_t ns_id, int l_row, colnr_T l_col, int u_r
   return marks_cleared;
 }
 
-// Returns the position of marks between a range,
+/// @return  the position of marks between a range,
-// marks found at the start or end index will be included,
+///          marks found at the start or end index will be included.
-// if upper_lnum or upper_col are negative the buffer
+///
-// will be searched to the start, or end
+/// if upper_lnum or upper_col are negative the buffer
-// dir can be set to control the order of the array
+/// will be searched to the start, or end
-// amount = amount of marks to find or -1 for all
+/// dir can be set to control the order of the array
+/// amount = amount of marks to find or -1 for all
 ExtmarkInfoArray extmark_get(buf_T *buf, uint32_t ns_id, int l_row, colnr_T l_col, int u_row,
                              colnr_T u_col, int64_t amount, bool reverse)
 {
@@ -334,7 +336,7 @@ next_mark:
   return array;
 }
 
-// Lookup an extmark by id
+/// Lookup an extmark by id
 ExtmarkInfo extmark_from_id(buf_T *buf, uint32_t ns_id, uint32_t id)
 {
   ExtmarkInfo ret = { 0, 0, -1, -1, -1, -1, false, false, DECORATION_INIT };
@@ -359,7 +361,7 @@ ExtmarkInfo extmark_from_id(buf_T *buf, uint32_t ns_id, uint32_t id)
 }
 
 
-// free extmarks from the buffer
+/// free extmarks from the buffer
 void extmark_free_all(buf_T *buf)
 {
   if (!map_size(buf->b_extmark_ns)) {
@@ -389,7 +391,7 @@ void extmark_free_all(buf_T *buf)
 }
 
 
-// Save info for undo/redo of set marks
+/// Save info for undo/redo of set marks
 static void u_extmark_set(buf_T *buf, uint64_t mark, int row, colnr_T col)
 {
   u_header_T *uhp = u_force_get_undo_header(buf);
@@ -499,7 +501,7 @@ void extmark_apply_undo(ExtmarkUndoObject undo_info, bool undo)
 }
 
 
-// Adjust extmark row for inserted/deleted rows (columns stay fixed).
+/// Adjust extmark row for inserted/deleted rows (columns stay fixed).
 void extmark_adjust(buf_T *buf, linenr_T line1, linenr_T line2, long amount, long amount_after,
                     ExtmarkOp undo)
 {

src/nvim/file_search.c

@@ -529,9 +529,7 @@ error_return:
   return NULL;
 }
 
-/*
+/// @return  the stopdir string.  Check that ';' is not escaped.
- * Get the stopdir string.  Check that ';' is not escaped.
- */
 char_u *vim_findfile_stopdir(char_u *buf)
 {
   char_u *r_ptr = buf;
@@ -554,9 +552,7 @@ char_u *vim_findfile_stopdir(char_u *buf)
   return r_ptr;
 }
 
-/*
+/// Clean up the given search context. Can handle a NULL pointer.
- * Clean up the given search context. Can handle a NULL pointer.
- */
 void vim_findfile_cleanup(void *ctx)
 {
   if (ctx == NULL) {
@@ -568,18 +564,19 @@ void vim_findfile_cleanup(void *ctx)
   xfree(ctx);
 }
 
-/*
+/// Find a file in a search context.
- * Find a file in a search context.
+/// The search context was created with vim_findfile_init() above.
- * The search context was created with vim_findfile_init() above.
+///
- * Return a pointer to an allocated file name or NULL if nothing found.
+/// To get all matching files call this function until you get NULL.
- * To get all matching files call this function until you get NULL.
+///
- *
+/// If the passed search_context is NULL, NULL is returned.
- * If the passed search_context is NULL, NULL is returned.
+///
- *
+/// The search algorithm is depth first. To change this replace the
- * The search algorithm is depth first. To change this replace the
+/// stack with a list (don't forget to leave partly searched directories on the
- * stack with a list (don't forget to leave partly searched directories on the
+/// top of the list).
- * top of the list).
+///
- */
+/// @return  a pointer to an allocated file name or,
+///          NULL if nothing found.
 char_u *vim_findfile(void *search_ctx_arg)
 {
   char_u *file_path;
@@ -999,10 +996,8 @@ fail:
   return NULL;
 }
 
-/*
+/// Free the list of lists of visited files and directories
- * Free the list of lists of visited files and directories
+/// Can handle it if the passed search_context is NULL;
- * Can handle it if the passed search_context is NULL;
- */
 void vim_findfile_free_visited(void *search_ctx_arg)
 {
   ff_search_ctx_T *search_ctx;
@@ -1044,10 +1039,8 @@ static void ff_free_visited_list(ff_visited_T *vl)
   vl = NULL;
 }
 
-/*
+/// @return  the already visited list for the given filename. If none is found it
- * Returns the already visited list for the given filename. If none is found it
+///          allocates a new one.
- * allocates a new one.
- */
 static ff_visited_list_hdr_T *ff_get_visited_list(char_u *filename,
                                                   ff_visited_list_hdr_T **list_headp)
 {
@@ -1094,13 +1087,13 @@ static ff_visited_list_hdr_T *ff_get_visited_list(char_u *filename,
   return retptr;
 }
 
-// Check if two wildcard paths are equal.
+/// Check if two wildcard paths are equal.
-// They are equal if:
+/// They are equal if:
-//  - both paths are NULL
+///  - both paths are NULL
-//  - they have the same length
+///  - they have the same length
-//  - char by char comparison is OK
+///  - char by char comparison is OK
-//  - the only differences are in the counters behind a '**', so
+///  - the only differences are in the counters behind a '**', so
-//    '**\20' is equal to '**\24'
+///    '**\20' is equal to '**\24'
 static bool ff_wc_equal(char_u *s1, char_u *s2)
 {
   int i, j;
@@ -1134,11 +1127,10 @@ static bool ff_wc_equal(char_u *s1, char_u *s2)
   return s1[i] == s2[j];
 }
 
-/*
+/// maintains the list of already visited files and dirs
- * maintains the list of already visited files and dirs
+///
- * returns FAIL if the given file/dir is already in the list
+/// @return  FAIL if the given file/dir is already in the list or,
- * returns OK if it is newly added
+///          OK if it is newly added
- */
 static int ff_check_visited(ff_visited_T **visited_list, char_u *fname, char_u *wc_path)
 {
   ff_visited_T *vp;
@@ -1196,9 +1188,7 @@ static int ff_check_visited(ff_visited_T **visited_list, char_u *fname, char_u *
   return OK;
 }
 
-/*
+/// create stack element from given path pieces
- * create stack element from given path pieces
- */
 static ff_stack_T *ff_create_stack_element(char_u *fix_part, char_u *wc_part, int level,
                                            int star_star_empty)
 {
@@ -1226,9 +1216,7 @@ static ff_stack_T *ff_create_stack_element(char_u *fix_part, char_u *wc_part, in
   return new;
 }
 
-/*
+/// Push a dir on the directory stack.
- * Push a dir on the directory stack.
- */
 static void ff_push(ff_search_ctx_T *search_ctx, ff_stack_T *stack_ptr)
 {
   /* check for NULL pointer, not to return an error to the user, but
@@ -1239,10 +1227,9 @@ static void ff_push(ff_search_ctx_T *search_ctx, ff_stack_T *stack_ptr)
   }
 }
 
-/*
+/// Pop a dir from the directory stack.
- * Pop a dir from the directory stack.
+///
- * Returns NULL if stack is empty.
+/// @return  NULL if stack is empty.
- */
 static ff_stack_T *ff_pop(ff_search_ctx_T *search_ctx)
 {
   ff_stack_T *sptr;
@@ -1255,9 +1242,7 @@ static ff_stack_T *ff_pop(ff_search_ctx_T *search_ctx)
   return sptr;
 }
 
-/*
+/// free the given stack element
- * free the given stack element
- */
 static void ff_free_stack_element(ff_stack_T *const stack_ptr)
 {
   if (stack_ptr == NULL) {
@@ -1275,9 +1260,7 @@ static void ff_free_stack_element(ff_stack_T *const stack_ptr)
   xfree(stack_ptr);
 }
 
-/*
+/// Clear the search context, but NOT the visited list.
- * Clear the search context, but NOT the visited list.
- */
 static void ff_clear(ff_search_ctx_T *search_ctx)
 {
   ff_stack_T *sptr;
@@ -1311,10 +1294,9 @@ static void ff_clear(ff_search_ctx_T *search_ctx)
   search_ctx->ffsc_level = 0;
 }
 
-/*
+/// check if the given path is in the stopdirs
- * check if the given path is in the stopdirs
+///
- * returns TRUE if yes else FALSE
+/// @return  TRUE if yes else FALSE
- */
 static int ff_path_in_stoplist(char_u *path, int path_len, char_u **stopdirs_v)
 {
   int i = 0;
@@ -1670,7 +1652,8 @@ void do_autocmd_dirchanged(char *new_dir, CdScope scope, CdCause cause, bool pre
 
 /// Change to a file's directory.
 /// Caller must call shorten_fnames()!
-/// @return OK or FAIL
+///
+/// @return  OK or FAIL
 int vim_chdirfile(char_u *fname, CdCause cause)
 {
   char dir[MAXPATHL];

src/nvim/fileio.c

@@ -2033,9 +2033,7 @@ void prep_exarg(exarg_T *eap, const buf_T *buf)
   eap->forceit = FALSE;
 }
 
-/*
+/// Set default or forced 'fileformat' and 'binary'.
- * Set default or forced 'fileformat' and 'binary'.
- */
 void set_file_options(int set_options, exarg_T *eap)
 {
   // set default 'fileformat'
@@ -2056,9 +2054,7 @@ void set_file_options(int set_options, exarg_T *eap)
   }
 }
 
-/*
+/// Set forced 'fileencoding'.
- * Set forced 'fileencoding'.
- */
 void set_forced_fenc(exarg_T *eap)
 {
   if (eap->force_enc != 0) {
@@ -2068,12 +2064,12 @@ void set_forced_fenc(exarg_T *eap)
   }
 }
 
-// Find next fileencoding to use from 'fileencodings'.
+/// Find next fileencoding to use from 'fileencodings'.
-// "pp" points to fenc_next.  It's advanced to the next item.
+/// "pp" points to fenc_next.  It's advanced to the next item.
-// When there are no more items, an empty string is returned and *pp is set to
+/// When there are no more items, an empty string is returned and *pp is set to
-// NULL.
+/// NULL.
-// When *pp is not set to NULL, the result is in allocated memory and "alloced"
+/// When *pp is not set to NULL, the result is in allocated memory and "alloced"
-// is set to true.
+/// is set to true.
 static char_u *next_fenc(char_u **pp, bool *alloced)
   FUNC_ATTR_NONNULL_ALL FUNC_ATTR_NONNULL_RET
 {
@@ -2149,10 +2145,8 @@ static char_u *readfile_charconvert(char_u *fname, char_u *fenc, int *fdp)
 }
 
 
-/*
+/// Read marks for the current buffer from the ShaDa file, when we support
- * Read marks for the current buffer from the ShaDa file, when we support
+/// buffer marks and the buffer has a name.
- * buffer marks and the buffer has a name.
- */
 static void check_marks_read(void)
 {
   if (!curbuf->b_marks_read && get_shada_parameter('\'') > 0
@@ -3761,10 +3755,8 @@ nofail:
 #undef SET_ERRMSG_NUM
 }
 
-/*
+/// Set the name of the current buffer.  Use when the buffer doesn't have a
- * Set the name of the current buffer.  Use when the buffer doesn't have a
+/// name and a ":r" or ":w" command with a file name is used.
- * name and a ":r" or ":w" command with a file name is used.
- */
 static int set_rw_fname(char_u *fname, char_u *sfname)
 {
   buf_T *buf = curbuf;
@@ -3854,9 +3846,7 @@ static bool msg_add_fileformat(int eol_type)
   return false;
 }
 
-/*
+/// Append line and character count to IObuff.
- * Append line and character count to IObuff.
- */
 void msg_add_lines(int insert_space, long lnum, off_T nchars)
 {
   char_u *p;
@@ -3880,20 +3870,16 @@ void msg_add_lines(int insert_space, long lnum, off_T nchars)
   }
 }
 
-/*
+/// Append message for missing line separator to IObuff.
- * Append message for missing line separator to IObuff.
- */
 static void msg_add_eol(void)
 {
   STRCAT(IObuff,
          shortmess(SHM_LAST) ? _("[noeol]") : _("[Incomplete last line]"));
 }
 
-/*
+/// Check modification time of file, before writing to it.
- * Check modification time of file, before writing to it.
+/// The size isn't checked, because using a tool like "gzip" takes care of
- * The size isn't checked, because using a tool like "gzip" takes care of
+/// using the same timestamp but can't set the size.
- * using the same timestamp but can't set the size.
- */
 static int check_mtime(buf_T *buf, FileInfo *file_info)
 {
   if (buf->b_mtime_read != 0
@@ -3925,12 +3911,10 @@ static bool time_differs(const FileInfo *file_info, long mtime, long mtime_ns) F
 #endif
 }
 
-/*
+/// Call write() to write a number of bytes to the file.
- * Call write() to write a number of bytes to the file.
+/// Handles 'encoding' conversion.
- * Handles 'encoding' conversion.
+///
- *
+/// @return  FAIL for failure, OK otherwise.
- * Return FAIL for failure, OK otherwise.
- */
 static int buf_write_bytes(struct bw_info *ip)
 {
   int wlen;
@@ -4258,12 +4242,11 @@ static int get_fio_flags(const char_u *name)
 }
 
 
-/*
+/// Check for a Unicode BOM (Byte Order Mark) at the start of p[size].
- * Check for a Unicode BOM (Byte Order Mark) at the start of p[size].
+/// "size" must be at least 2.
- * "size" must be at least 2.
+///
- * Return the name of the encoding and set "*lenp" to the length.
+/// @return  the name of the encoding and set "*lenp" to the length or,
- * Returns NULL when no BOM found.
+///          NULL when no BOM found.
- */
 static char_u *check_for_bom(char_u *p, long size, int *lenp, int flags)
 {
   char *name = NULL;
@@ -4304,10 +4287,9 @@ static char_u *check_for_bom(char_u *p, long size, int *lenp, int flags)
   return (char_u *)name;
 }
 
-/*
+/// Generate a BOM in "buf[4]" for encoding "name".
- * Generate a BOM in "buf[4]" for encoding "name".
+///
- * Return the length of the BOM (zero when no BOM).
+/// @return  the length of the BOM (zero when no BOM).
- */
 static int make_bom(char_u *buf, char_u *name)
 {
   int flags;
@@ -4332,10 +4314,12 @@ static int make_bom(char_u *buf, char_u *name)
 }
 
 /// Shorten filename of a buffer.
-/// When "force" is TRUE: Use full path from now on for files currently being
+///
-/// edited, both for file name and swap file name.  Try to shorten the file
+/// @param force  when TRUE: Use full path from now on for files currently being
-/// names a bit, if safe to do so.
+///               edited, both for file name and swap file name.  Try to shorten the file
-/// When "force" is FALSE: Only try to shorten absolute file names.
+///               names a bit, if safe to do so.
+///               when FALSE: Only try to shorten absolute file names.
+///
 /// For buffers that have buftype "nofile" or "scratch": never change the file
 /// name.
 void shorten_buf_fname(buf_T *buf, char_u *dirname, int force)
@@ -4513,7 +4497,8 @@ bool vim_fgets(char_u *buf, int size, FILE *fp) FUNC_ATTR_NONNULL_ALL
 }
 
 /// Read 2 bytes from "fd" and turn them into an int, MSB first.
-/// Returns -1 when encountering EOF.
+///
+/// @return  -1 when encountering EOF.
 int get2c(FILE *fd)
 {
   const int n = getc(fd);
@@ -4528,7 +4513,8 @@ int get2c(FILE *fd)
 }
 
 /// Read 3 bytes from "fd" and turn them into an int, MSB first.
-/// Returns -1 when encountering EOF.
+///
+/// @return  -1 when encountering EOF.
 int get3c(FILE *fd)
 {
   int n = getc(fd);
@@ -4548,7 +4534,8 @@ int get3c(FILE *fd)
 }
 
 /// Read 4 bytes from "fd" and turn them into an int, MSB first.
-/// Returns -1 when encountering EOF.
+///
+/// @return  -1 when encountering EOF.
 int get4c(FILE *fd)
 {
   // Use unsigned rather than int otherwise result is undefined
@@ -4579,7 +4566,8 @@ int get4c(FILE *fd)
 }
 
 /// Read 8 bytes from `fd` and turn them into a time_t, MSB first.
-/// Returns -1 when encountering EOF.
+///
+/// @return  -1 when encountering EOF.
 time_t get8ctime(FILE *fd)
 {
   time_t n = 0;
@@ -4595,7 +4583,8 @@ time_t get8ctime(FILE *fd)
 }
 
 /// Reads a string of length "cnt" from "fd" into allocated memory.
-/// @return pointer to the string or NULL when unable to read that many bytes.
+///
+/// @return  pointer to the string or NULL when unable to read that many bytes.
 char *read_string(FILE *fd, size_t cnt)
 {
   char *str = xmallocz(cnt);
@@ -4611,7 +4600,8 @@ char *read_string(FILE *fd, size_t cnt)
 }
 
 /// Writes a number to file "fd", most significant bit first, in "len" bytes.
-/// @returns false in case of an error.
+///
+/// @return  false in case of an error.
 bool put_bytes(FILE *fd, uintmax_t number, size_t len)
 {
   assert(len > 0);
@@ -4624,7 +4614,8 @@ bool put_bytes(FILE *fd, uintmax_t number, size_t len)
 }
 
 /// Writes time_t to file "fd" in 8 bytes.
-/// @returns FAIL when the write failed.
+///
+/// @return  FAIL when the write failed.
 int put_time(FILE *fd, time_t time_)
 {
   uint8_t buf[8];
@@ -4635,7 +4626,7 @@ int put_time(FILE *fd, time_t time_)
 /// os_rename() only works if both files are on the same file system, this
 /// function will (attempts to?) copy the file across if rename fails -- webb
 ///
-/// @return -1 for failure, 0 for success
+/// @return  -1 for failure, 0 for success
 int vim_rename(const char_u *from, const char_u *to)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -4860,11 +4851,10 @@ int check_timestamps(int focus)
   return didit;
 }
 
-/*
+/// Move all the lines from buffer "frombuf" to buffer "tobuf".
- * Move all the lines from buffer "frombuf" to buffer "tobuf".
+///
- * Return OK or FAIL.  When FAIL "tobuf" is incomplete and/or "frombuf" is not
+/// @return  OK or FAIL.
- * empty.
+///          When FAIL "tobuf" is incomplete and/or "frombuf" is not empty.
- */
 static int move_lines(buf_T *frombuf, buf_T *tobuf)
 {
   buf_T *tbuf = curbuf;
@@ -4903,9 +4893,10 @@ static int move_lines(buf_T *frombuf, buf_T *tobuf)
 
 /// Check if buffer "buf" has been changed.
 /// Also check if the file for a new buffer unexpectedly appeared.
-/// return 1 if a changed buffer was found.
+///
-/// return 2 if a message has been displayed.
+/// @return  1 if a changed buffer was found or,
-/// return 0 otherwise.
+///          2 if a message has been displayed or,
+///          0 otherwise.
 int buf_check_timestamp(buf_T *buf)
   FUNC_ATTR_NONNULL_ALL
 {
@@ -5280,10 +5271,8 @@ void buf_store_file_info(buf_T *buf, FileInfo *file_info)
   buf->b_orig_mode = (int)file_info->stat.st_mode;
 }
 
-/*
+/// Adjust the line with missing eol, used for the next write.
- * Adjust the line with missing eol, used for the next write.
+/// Used for do_filter(), when the input lines for the filter are deleted.
- * Used for do_filter(), when the input lines for the filter are deleted.
- */
 void write_lnum_adjust(linenr_T offset)
 {
   if (curbuf->b_no_eol_lnum != 0) {     // only if there is a missing eol
@@ -5355,8 +5344,10 @@ static void vim_maketempdir(void)
 }
 
 /// Delete "name" and everything in it, recursively.
+///
 /// @param name The path which should be deleted.
-/// @return 0 for success, -1 if some file was not deleted.
+///
+/// @return  0 for success, -1 if some file was not deleted.
 int delete_recursive(const char *name)
 {
   int result = 0;
@@ -5400,8 +5391,8 @@ void vim_deltempdir(void)
   }
 }
 
-/// Get the name of temp directory. This directory would be created on the first
+/// @return  the name of temp directory. This directory would be created on the first
-/// call to this function.
+///          call to this function.
 char_u *vim_gettempdir(void)
 {
   if (vim_tempdir == NULL) {
@@ -5435,8 +5426,8 @@ static bool vim_settempdir(char *tempdir)
 ///
 /// @note The temp file is NOT created.
 ///
-/// @return pointer to the temp file name or NULL if Neovim can't create
+/// @return  pointer to the temp file name or NULL if Neovim can't create
-///         temporary directory for its own temporary files.
+///          temporary directory for its own temporary files.
 char_u *vim_tempname(void)
 {
   // Temp filename counter.
@@ -5747,10 +5738,9 @@ char_u *file_pat_to_reg_pat(const char_u *pat, const char_u *pat_end, char *allo
 }
 
 #if defined(EINTR)
-/*
+
- * Version of read() that retries when interrupted by EINTR (possibly
+/// Version of read() that retries when interrupted by EINTR (possibly
- * by a SIGWINCH).
+/// by a SIGWINCH).
- */
 long read_eintr(int fd, void *buf, size_t bufsize)
 {
   long ret;
@@ -5764,10 +5754,8 @@ long read_eintr(int fd, void *buf, size_t bufsize)
   return ret;
 }
 
-/*
+/// Version of write() that retries when interrupted by EINTR (possibly
- * Version of write() that retries when interrupted by EINTR (possibly
+/// by a SIGWINCH).
- * by a SIGWINCH).
- */
 long write_eintr(int fd, void *buf, size_t bufsize)
 {
   long ret = 0;