IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #17731 from dundargoc/doxygen/ex_eval

Browse Source 
refactor(ex_eval): convert function comments to doxygen format
This commit is contained in:
bfredl 2022-03-15 21:18:08 +01:00 committed by GitHub
commit a1a8cbe9e4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 128 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

315
src/nvim/ex_eval.c
View File

@ -88,27 +88,26 @@
*/ */
static int cause_abort = FALSE; static int cause_abort = FALSE;
// Return true when immediately aborting on error, or when an interrupt /// @return true when immediately aborting on error, or when an interrupt
// occurred or an exception was thrown but not caught. Use for ":{range}call" /// occurred or an exception was thrown but not caught.
// to check whether an aborted function that does not handle a range itself ///
// should be called again for the next line in the range. Also used for /// Use for ":{range}call" to check whether an aborted function that does not
// cancelling expression evaluation after a function call caused an immediate /// handle a range itself should be called again for the next line in the range.
// abort. Note that the first emsg() call temporarily resets "force_abort" /// Also used for cancelling expression evaluation after a function call caused
// until the throw point for error messages has been reached. That is, during /// an immediate abort. Note that the first emsg() call temporarily resets
// cancellation of an expression evaluation after an aborting function call or /// "force_abort" until the throw point for error messages has been reached.
// due to a parsing error, aborting() always returns the same value. /// That is, during cancellation of an expression evaluation after an aborting
// "got_int" is also set by calling interrupt(). /// function call or due to a parsing error, aborting() always returns the same
/// value. "got_int" is also set by calling interrupt().
int aborting(void) int aborting(void)
{ {
return (did_emsg && force_abort) || got_int || current_exception; return (did_emsg && force_abort) || got_int || current_exception;
} }
/* /// The value of "force_abort" is temporarily reset by the first emsg() call
* The value of "force_abort" is temporarily reset by the first emsg() call /// during an expression evaluation, and "cause_abort" is used instead. It might
* during an expression evaluation, and "cause_abort" is used instead. It might /// be necessary to restore "force_abort" even before the throw point for the
* be necessary to restore "force_abort" even before the throw point for the /// error message has been reached. update_force_abort() should be called then.
* error message has been reached. update_force_abort() should be called then.
*/
void update_force_abort(void) void update_force_abort(void)
{ {
if (cause_abort) { if (cause_abort) {
@ -116,23 +115,19 @@ void update_force_abort(void)
} }
} }
/* /// @return TRUE if a command with a subcommand resulting in "retcode" should
* Return TRUE if a command with a subcommand resulting in "retcode" should /// abort the script processing. Can be used to suppress an autocommand after
* abort the script processing. Can be used to suppress an autocommand after /// execution of a failing subcommand as long as the error message has not been
* execution of a failing subcommand as long as the error message has not been /// displayed and actually caused the abortion.
* displayed and actually caused the abortion.
*/
int should_abort(int retcode) int should_abort(int retcode)
{ {
return (retcode == FAIL && trylevel != 0 && !emsg_silent) || aborting(); return (retcode == FAIL && trylevel != 0 && !emsg_silent) || aborting();
} }
/* /// @return TRUE if a function with the "abort" flag should not be considered
* Return TRUE if a function with the "abort" flag should not be considered /// ended on an error. This means that parsing commands is continued in order
* ended on an error. This means that parsing commands is continued in order /// to find finally clauses to be executed, and that some errors in skipped
* to find finally clauses to be executed, and that some errors in skipped /// commands are still reported.
* commands are still reported.
*/
int aborted_in_try(void) int aborted_in_try(void)
{ {
// This function is only called after an error. In this case, "force_abort" // This function is only called after an error. In this case, "force_abort"
@ -140,13 +135,15 @@ int aborted_in_try(void)
return force_abort; return force_abort;
} }
// cause_errthrow(): Cause a throw of an error exception if appropriate. /// cause_errthrow(): Cause a throw of an error exception if appropriate.
// Return true if the error message should not be displayed by emsg(). ///
// Sets "ignore", if the emsg() call should be ignored completely. /// @return true if the error message should not be displayed by emsg().
// ///
// When several messages appear in the same command, the first is usually the /// Sets "ignore", if the emsg() call should be ignored completely.
// most specific one and used as the exception value. The "severe" flag can be ///
// set to true, if a later but severer message should be used instead. /// When several messages appear in the same command, the first is usually the
/// most specific one and used as the exception value. The "severe" flag can be
/// set to true, if a later but severer message should be used instead.
bool cause_errthrow(const char_u *mesg, bool severe, bool *ignore) bool cause_errthrow(const char_u *mesg, bool severe, bool *ignore)
FUNC_ATTR_NONNULL_ALL FUNC_ATTR_NONNULL_ALL
{ {
@ -279,9 +276,7 @@ bool cause_errthrow(const char_u *mesg, bool severe, bool *ignore)
} }
} }
/* /// Free a "msg_list" and the messages it contains.
* Free a "msg_list" and the messages it contains.
*/
static void free_msglist(struct msglist *l) static void free_msglist(struct msglist *l)
{ {
struct msglist *messages, *next; struct msglist *messages, *next;
@ -295,21 +290,17 @@ static void free_msglist(struct msglist *l)
} }
} }
/* /// Free global "*msg_list" and the messages it contains, then set "*msg_list"
* Free global "*msg_list" and the messages it contains, then set "*msg_list" /// to NULL.
* to NULL.
*/
void free_global_msglist(void) void free_global_msglist(void)
{ {
free_msglist(*msg_list); free_msglist(*msg_list);
*msg_list = NULL; *msg_list = NULL;
} }
/* /// Throw the message specified in the call to cause_errthrow() above as an
* Throw the message specified in the call to cause_errthrow() above as an /// error exception. If cstack is NULL, postpone the throw until do_cmdline()
* error exception. If cstack is NULL, postpone the throw until do_cmdline() /// has returned (see do_one_cmd()).
* has returned (see do_one_cmd()).
*/
void do_errthrow(cstack_T *cstack, char_u *cmdname) void do_errthrow(cstack_T *cstack, char_u *cmdname)
{ {
/* /*
@ -339,11 +330,11 @@ void do_errthrow(cstack_T *cstack, char_u *cmdname)
*msg_list = NULL; *msg_list = NULL;
} }
/* /// do_intthrow(): Replace the current exception by an interrupt or interrupt
* do_intthrow(): Replace the current exception by an interrupt or interrupt /// exception if appropriate.
* exception if appropriate. Return TRUE if the current exception is discarded, ///
* FALSE otherwise. /// @return TRUE if the current exception is discarded or,
*/ /// FALSE otherwise.
int do_intthrow(cstack_T *cstack) int do_intthrow(cstack_T *cstack)
{ {
// If no interrupt occurred or no try conditional is active and no exception // If no interrupt occurred or no try conditional is active and no exception
@ -386,7 +377,7 @@ int do_intthrow(cstack_T *cstack)
return true; return true;
} }
// Get an exception message that is to be stored in current_exception->value. /// Get an exception message that is to be stored in current_exception->value.
char *get_exception_string(void *value, except_type_T type, char_u *cmdname, int *should_free) char *get_exception_string(void *value, except_type_T type, char_u *cmdname, int *should_free)
{ {
char *ret, *mesg; char *ret, *mesg;
@ -445,10 +436,12 @@ char *get_exception_string(void *value, except_type_T type, char_u *cmdname, int
} }
// Throw a new exception. Return FAIL when out of memory or it was tried to /// Throw a new exception. "value" is the exception string for a
// throw an illegal user exception. "value" is the exception string for a /// user or interrupt exception, or points to a message list in case of an
// user or interrupt exception, or points to a message list in case of an /// error exception.
// error exception. ///
/// @return FAIL when out of memory or it was tried to throw an illegal user
/// exception.
static int throw_exception(void *value, except_type_T type, char_u *cmdname) static int throw_exception(void *value, except_type_T type, char_u *cmdname)
{ {
except_T *excp; except_T *excp;
@ -524,10 +517,8 @@ fail:
return FAIL; return FAIL;
} }
/* /// Discard an exception. "was_finished" is set when the exception has been
* Discard an exception. "was_finished" is set when the exception has been /// caught and the catch clause has been ended normally.
* caught and the catch clause has been ended normally.
*/
static void discard_exception(except_T *excp, bool was_finished) static void discard_exception(except_T *excp, bool was_finished)
{ {
char_u *saved_IObuff; char_u *saved_IObuff;
@ -579,9 +570,7 @@ static void discard_exception(except_T *excp, bool was_finished)
xfree(excp); xfree(excp);
} }
/* /// Discard the exception currently being thrown.
* Discard the exception currently being thrown.
*/
void discard_current_exception(void) void discard_current_exception(void)
{ {
if (current_exception != NULL) { if (current_exception != NULL) {
@ -592,9 +581,7 @@ void discard_current_exception(void)
need_rethrow = false; need_rethrow = false;
} }
/* /// Put an exception on the caught stack.
* Put an exception on the caught stack.
*/
static void catch_exception(except_T *excp) static void catch_exception(except_T *excp)
{ {
excp->caught = caught_stack; excp->caught = caught_stack;
@ -640,9 +627,7 @@ static void catch_exception(except_T *excp)
} }
} }
/* /// Remove an exception from the caught stack.
* Remove an exception from the caught stack.
*/
static void finish_exception(except_T *excp) static void finish_exception(except_T *excp)
{ {
if (excp != caught_stack) { if (excp != caught_stack) {
@ -682,13 +667,11 @@ static void finish_exception(except_T *excp)
#define RP_RESUME 1 #define RP_RESUME 1
#define RP_DISCARD 2 #define RP_DISCARD 2
/* /// Report information about something pending in a finally clause if required by
* Report information about something pending in a finally clause if required by /// the 'verbose' option or when debugging. "action" tells whether something is
* the 'verbose' option or when debugging. "action" tells whether something is /// made pending or something pending is resumed or discarded. "pending" tells
* made pending or something pending is resumed or discarded. "pending" tells /// what is pending. "value" specifies the return value for a pending ":return"
* what is pending. "value" specifies the return value for a pending ":return" /// or the exception value for a pending exception.
* or the exception value for a pending exception.
*/
static void report_pending(int action, int pending, void *value) static void report_pending(int action, int pending, void *value)
{ {
char *mesg; char *mesg;
@ -764,10 +747,8 @@ static void report_pending(int action, int pending, void *value)
} }
} }
/* /// If something is made pending in a finally clause, report it if required by
* If something is made pending in a finally clause, report it if required by /// the 'verbose' option or when debugging.
* the 'verbose' option or when debugging.
*/
void report_make_pending(int pending, void *value) void report_make_pending(int pending, void *value)
{ {
if (p_verbose >= 14 || debug_break_level > 0) { if (p_verbose >= 14 || debug_break_level > 0) {
@ -781,10 +762,8 @@ void report_make_pending(int pending, void *value)
} }
} }
/* /// If something pending in a finally clause is resumed at the ":endtry", report
* If something pending in a finally clause is resumed at the ":endtry", report /// it if required by the 'verbose' option or when debugging.
* it if required by the 'verbose' option or when debugging.
*/
void report_resume_pending(int pending, void *value) void report_resume_pending(int pending, void *value)
{ {
if (p_verbose >= 14 || debug_break_level > 0) { if (p_verbose >= 14 || debug_break_level > 0) {
@ -798,10 +777,8 @@ void report_resume_pending(int pending, void *value)
} }
} }
/* /// If something pending in a finally clause is discarded, report it if required
* If something pending in a finally clause is discarded, report it if required /// by the 'verbose' option or when debugging.
* by the 'verbose' option or when debugging.
*/
void report_discard_pending(int pending, void *value) void report_discard_pending(int pending, void *value)
{ {
if (p_verbose >= 14 || debug_break_level > 0) { if (p_verbose >= 14 || debug_break_level > 0) {
@ -815,7 +792,7 @@ void report_discard_pending(int pending, void *value)
} }
} }
// ":eval". /// Handle ":eval".
void ex_eval(exarg_T *eap) void ex_eval(exarg_T *eap)
{ {
typval_T tv; typval_T tv;
@ -825,9 +802,7 @@ void ex_eval(exarg_T *eap)
} }
} }
/* /// Handle ":if".
* ":if".
*/
void ex_if(exarg_T *eap) void ex_if(exarg_T *eap)
{ {
int skip; int skip;
@ -856,9 +831,7 @@ void ex_if(exarg_T *eap)
} }
} }
/* /// Handle ":endif".
* ":endif".
*/
void ex_endif(exarg_T *eap) void ex_endif(exarg_T *eap)
{ {
did_endif = true; did_endif = true;
@ -883,9 +856,7 @@ void ex_endif(exarg_T *eap)
} }
} }
/* /// Handle ":else" and ":elseif".
* ":else" and ":elseif".
*/
void ex_else(exarg_T *eap) void ex_else(exarg_T *eap)
{ {
int result; int result;
@ -958,9 +929,7 @@ void ex_else(exarg_T *eap)
} }
} }
/* /// Handle ":while" and ":for".
* Handle ":while" and ":for".
*/
void ex_while(exarg_T *eap) void ex_while(exarg_T *eap)
{ {
bool error; bool error;
@ -1041,9 +1010,7 @@ void ex_while(exarg_T *eap)
} }
} }
/* /// Handle ":continue"
* ":continue"
*/
void ex_continue(exarg_T *eap) void ex_continue(exarg_T *eap)
{ {
int idx; int idx;
@ -1075,9 +1042,7 @@ void ex_continue(exarg_T *eap)
} }
} }
/* /// Handle ":break"
* ":break"
*/
void ex_break(exarg_T *eap) void ex_break(exarg_T *eap)
{ {
int idx; int idx;
@ -1098,9 +1063,7 @@ void ex_break(exarg_T *eap)
} }
} }
/* /// Handle ":endwhile" and ":endfor"
* ":endwhile" and ":endfor"
*/
void ex_endwhile(exarg_T *eap) void ex_endwhile(exarg_T *eap)
{ {
cstack_T *const cstack = eap->cstack; cstack_T *const cstack = eap->cstack;
@ -1175,9 +1138,7 @@ void ex_endwhile(exarg_T *eap)
} }
/* /// Handle ":throw expr"
* ":throw expr"
*/
void ex_throw(exarg_T *eap) void ex_throw(exarg_T *eap)
{ {
const char *arg = (const char *)eap->arg; const char *arg = (const char *)eap->arg;
@ -1202,11 +1163,9 @@ void ex_throw(exarg_T *eap)
} }
} }
/* /// Throw the current exception through the specified cstack. Common routine
* Throw the current exception through the specified cstack. Common routine /// for ":throw" (user exception) and error and interrupt exceptions. Also
* for ":throw" (user exception) and error and interrupt exceptions. Also /// used for rethrowing an uncaught exception.
* used for rethrowing an uncaught exception.
*/
void do_throw(cstack_T *cstack) void do_throw(cstack_T *cstack)
{ {
int idx; int idx;
@ -1263,9 +1222,7 @@ void do_throw(cstack_T *cstack)
} }
} }
/* /// Handle ":try"
* ":try"
*/
void ex_try(exarg_T *eap) void ex_try(exarg_T *eap)
{ {
int skip; int skip;
@ -1315,9 +1272,7 @@ void ex_try(exarg_T *eap)
} }
} }
/* /// Handle ":catch /{pattern}/" and ":catch"
* ":catch /{pattern}/" and ":catch"
*/
void ex_catch(exarg_T *eap) void ex_catch(exarg_T *eap)
{ {
int idx = 0; int idx = 0;
@ -1471,9 +1426,7 @@ void ex_catch(exarg_T *eap)
} }
} }
/* /// Handle ":finally"
* ":finally"
*/
void ex_finally(exarg_T *eap) void ex_finally(exarg_T *eap)
{ {
int idx; int idx;
@ -1595,9 +1548,7 @@ void ex_finally(exarg_T *eap)
} }
} }
/* /// Handle ":endtry"
* ":endtry"
*/
void ex_endtry(exarg_T *eap) void ex_endtry(exarg_T *eap)
{ {
int idx; int idx;
@ -1784,14 +1735,12 @@ void ex_endtry(exarg_T *eap)
* error/interrupt/exception state. * error/interrupt/exception state.
*/ */
/* /// This function works a bit like ex_finally() except that there was not
* This function works a bit like ex_finally() except that there was not /// actually an extra try block around the part that failed and an error or
* actually an extra try block around the part that failed and an error or /// interrupt has not (yet) been converted to an exception. This function
* interrupt has not (yet) been converted to an exception. This function /// saves the error/interrupt/ exception state and prepares for the call to
* saves the error/interrupt/ exception state and prepares for the call to /// do_cmdline() that is going to be made for the cleanup autocommand
* do_cmdline() that is going to be made for the cleanup autocommand /// execution.
* execution.
*/
void enter_cleanup(cleanup_T *csp) void enter_cleanup(cleanup_T *csp)
{ {
int pending = CSTP_NONE; int pending = CSTP_NONE;
@ -1834,21 +1783,19 @@ void enter_cleanup(cleanup_T *csp)
} }
} }
/* /// This function is a bit like ex_endtry() except that there was not actually
* See comment above enter_cleanup() for how this function is used. /// an extra try block around the part that failed and an error or interrupt
* /// had not (yet) been converted to an exception when the cleanup autocommand
* This function is a bit like ex_endtry() except that there was not actually /// sequence was invoked.
* an extra try block around the part that failed and an error or interrupt ///
* had not (yet) been converted to an exception when the cleanup autocommand /// See comment above enter_cleanup() for how this function is used.
* sequence was invoked. ///
* /// This function has to be called with the address of the cleanup_T structure
* This function has to be called with the address of the cleanup_T structure /// filled by enter_cleanup() as an argument; it restores the error/interrupt/
* filled by enter_cleanup() as an argument; it restores the error/interrupt/ /// exception state saved by that function - except there was an aborting
* exception state saved by that function - except there was an aborting /// error, an interrupt or an uncaught exception during execution of the
* error, an interrupt or an uncaught exception during execution of the /// cleanup autocommands. In the latter case, the saved error/interrupt/
* cleanup autocommands. In the latter case, the saved error/interrupt/ /// exception state is discarded.
* exception state is discarded.
*/
void leave_cleanup(cleanup_T *csp) void leave_cleanup(cleanup_T *csp)
{ {
int pending = csp->pending; int pending = csp->pending;
@ -1913,22 +1860,25 @@ void leave_cleanup(cleanup_T *csp)
} }
/* /// Make conditionals inactive and discard what's pending in finally clauses
* Make conditionals inactive and discard what's pending in finally clauses /// until the conditional type searched for or a try conditional not in its
* until the conditional type searched for or a try conditional not in its /// finally clause is reached. If this is in an active catch clause, finish
* finally clause is reached. If this is in an active catch clause, finish /// the caught exception.
* the caught exception. ///
* Return the cstack index where the search stopped. ///
* Values used for "searched_cond" are (CSF_WHILE | CSF_FOR) or CSF_TRY or 0, /// @param searched_cond Possible values are (CSF_WHILE | CSF_FOR) or CSF_TRY or 0,
* the latter meaning the innermost try conditional not in its finally clause. /// the latter meaning the innermost try conditional not
* "inclusive" tells whether the conditional searched for should be made /// in its finally clause.
* inactive itself (a try conditional not in its finally clause possibly find /// @param inclusive tells whether the conditional searched for should be made
* before is always made inactive). If "inclusive" is TRUE and /// inactive itself (a try conditional not in its finally
* "searched_cond" is CSF_TRY|CSF_SILENT, the saved former value of /// clause possibly find before is always made inactive).
* "emsg_silent", if reset when the try conditional finally reached was ///
* entered, is restored (used by ex_endtry()). This is normally done only /// If "inclusive" is TRUE and "searched_cond" is CSF_TRY|CSF_SILENT, the saved
* when such a try conditional is left. /// former value of "emsg_silent", if reset when the try conditional finally
*/ /// reached was entered, is restored (used by ex_endtry()). This is normally
/// done only when such a try conditional is left.
///
/// @return the cstack index where the search stopped.
int cleanup_conditionals(cstack_T *cstack, int searched_cond, int inclusive) int cleanup_conditionals(cstack_T *cstack, int searched_cond, int inclusive)
{ {
int idx; int idx;
@ -2037,9 +1987,7 @@ int cleanup_conditionals(cstack_T *cstack, int searched_cond, int inclusive)
return idx; return idx;
} }
/* /// @return an appropriate error message for a missing endwhile/endfor/endif.
* Return an appropriate error message for a missing endwhile/endfor/endif.
*/
static char *get_end_emsg(cstack_T *cstack) static char *get_end_emsg(cstack_T *cstack)
{ {
if (cstack->cs_flags[cstack->cs_idx] & CSF_WHILE) { if (cstack->cs_flags[cstack->cs_idx] & CSF_WHILE) {
@ -2052,13 +2000,11 @@ static char *get_end_emsg(cstack_T *cstack)
} }
/* /// Rewind conditionals until index "idx" is reached. "cond_type" and
* Rewind conditionals until index "idx" is reached. "cond_type" and /// "cond_level" specify a conditional type and the address of a level variable
* "cond_level" specify a conditional type and the address of a level variable /// which is to be decremented with each skipped conditional of the specified
* which is to be decremented with each skipped conditional of the specified /// type.
* type. /// Also free "for info" structures where needed.
* Also free "for info" structures where needed.
*/
void rewind_conditionals(cstack_T *cstack, int idx, int cond_type, int *cond_level) void rewind_conditionals(cstack_T *cstack, int idx, int cond_type, int *cond_level)
{ {
while (cstack->cs_idx > idx) { while (cstack->cs_idx > idx) {
@ -2072,17 +2018,13 @@ void rewind_conditionals(cstack_T *cstack, int idx, int cond_type, int *cond_lev
} }
} }
/* /// Handle ":endfunction" when not after a ":function"
* ":endfunction" when not after a ":function"
*/
void ex_endfunction(exarg_T *eap) void ex_endfunction(exarg_T *eap)
{ {
emsg(_("E193: :endfunction not inside a function")); emsg(_("E193: :endfunction not inside a function"));
} }
/* /// @return TRUE if the string "p" looks like a ":while" or ":for" command.
* Return TRUE if the string "p" looks like a ":while" or ":for" command.
*/
int has_loop_cmd(char_u *p) int has_loop_cmd(char_u *p)
{ {
int len; int len;
@ -2104,4 +2046,3 @@ int has_loop_cmd(char_u *p)
} }
return FALSE; return FALSE;
} }