From bd4622a0d01c7d882c37c46f6730567750dda657 Mon Sep 17 00:00:00 2001 From: Kurtis Rader Date: Tue, 19 Apr 2016 18:17:39 -0700 Subject: make comments Xcode friendly The OS X Xcode IDE has a weird requirement that block comments preceding a function or class definition must begin with three slashes rather than two if you want the comment displayed in the "Quick Help" window. --- src/builtin.cpp | 146 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 72 insertions(+), 74 deletions(-) (limited to 'src/builtin.cpp') diff --git a/src/builtin.cpp b/src/builtin.cpp index 87b69b6c..a2bf6736 100644 --- a/src/builtin.cpp +++ b/src/builtin.cpp @@ -71,7 +71,7 @@ // The send stuff to foreground message. #define FG_MSG _(L"Send job %d, '%ls' to foreground\n") -// Datastructure to describe a builtin. +/// Datastructure to describe a builtin. struct builtin_data_t { // Name of the builtin. const wchar_t *name; @@ -92,7 +92,7 @@ bool builtin_data_t::operator<(const builtin_data_t *other) const { return wcscmp(this->name, other->name) < 0; } -// Counts the number of non null pointers in the specified array. +/// Counts the number of non null pointers in the specified array. int builtin_count_args(const wchar_t *const *argv) { int argc = 1; while (argv[argc] != NULL) { @@ -101,8 +101,8 @@ int builtin_count_args(const wchar_t *const *argv) { return argc; } -// This function works like wperror, but it prints its result into the streams.err string instead of -// to stderr. Used by the builtin commands. +/// This function works like wperror, but it prints its result into the streams.err string instead +/// to stderr. Used by the builtin commands. static void builtin_wperror(const wchar_t *s, io_streams_t &streams) { char *err = strerror(errno); if (s != NULL) { @@ -116,7 +116,7 @@ static void builtin_wperror(const wchar_t *s, io_streams_t &streams) { } } -// Count the number of times the specified character occurs in the specified string. +/// Count the number of times the specified character occurs in the specified string. static int count_char(const wchar_t *str, wchar_t c) { int res = 0; for (; *str; str++) { @@ -148,10 +148,10 @@ wcstring builtin_help_get(parser_t &parser, io_streams_t &streams, const wchar_t return out; } -// Print help for the specified builtin. If \c b is sb_err, also print the line information. -// -// If \c b is the buffer representing standard error, and the help message is about to be printed to -// an interactive screen, it may be shortened to fit the screen. +/// Print help for the specified builtin. If \c b is sb_err, also print the line information. +/// +/// If \c b is the buffer representing standard error, and the help message is about to be printed +/// to an interactive screen, it may be shortened to fit the screen. void builtin_print_help(parser_t &parser, io_streams_t &streams, const wchar_t *cmd, output_stream_t &b) { bool is_stderr = (&b == &streams.err); @@ -227,14 +227,14 @@ void builtin_print_help(parser_t &parser, io_streams_t &streams, const wchar_t * } } -// Perform error reporting for encounter with unknown option. +/// Perform error reporting for encounter with unknown option. static void builtin_unknown_option(parser_t &parser, io_streams_t &streams, const wchar_t *cmd, const wchar_t *opt) { streams.err.append_format(BUILTIN_ERR_UNKNOWN, cmd, opt); builtin_print_help(parser, streams, cmd, streams.err); } -// Perform error reporting for encounter with missing argument. +/// Perform error reporting for encounter with missing argument. static void builtin_missing_argument(parser_t &parser, io_streams_t &streams, const wchar_t *cmd, const wchar_t *opt) { streams.err.append_format(BUILTIN_ERR_MISSING, cmd, opt); @@ -269,8 +269,8 @@ int builtin_test(parser_t &parser, io_streams_t &streams, wchar_t **argv); // builtin_string lives in builtin_string.cpp int builtin_string(parser_t &parser, io_streams_t &streams, wchar_t **argv); -// List a single key binding. -// Returns false if no binding with that sequence and mode exists. +/// List a single key binding. +/// Returns false if no binding with that sequence and mode exists. static bool builtin_bind_list_one(const wcstring &seq, const wcstring &bind_mode, io_streams_t &streams) { std::vector ecmds; @@ -317,7 +317,7 @@ static bool builtin_bind_list_one(const wcstring &seq, const wcstring &bind_mode return true; } -// List all current key bindings. +/// List all current key bindings. static void builtin_bind_list(const wchar_t *bind_mode, io_streams_t &streams) { const std::vector lst = input_mapping_get_names(); @@ -331,10 +331,10 @@ static void builtin_bind_list(const wchar_t *bind_mode, io_streams_t &streams) { } } -// Print terminfo key binding names to string buffer used for standard output. -// -// \param all if set, all terminfo key binding names will be printed. If not set, only ones that -// are defined for this terminal are printed. +/// Print terminfo key binding names to string buffer used for standard output. +/// +/// \param all if set, all terminfo key binding names will be printed. If not set, only ones that +/// are defined for this terminal are printed. static void builtin_bind_key_names(int all, io_streams_t &streams) { const wcstring_list_t names = input_terminfo_get_names(!all); for (size_t i = 0; i < names.size(); i++) { @@ -344,7 +344,7 @@ static void builtin_bind_key_names(int all, io_streams_t &streams) { } } -// Print all the special key binding functions to string buffer used for standard output. +/// Print all the special key binding functions to string buffer used for standard output. static void builtin_bind_function_names(io_streams_t &streams) { wcstring_list_t names = input_function_get_names(); @@ -354,7 +354,7 @@ static void builtin_bind_function_names(io_streams_t &streams) { } } -// Wraps input_terminfo_get_sequence(), appending the correct error messages as needed. +/// Wraps input_terminfo_get_sequence(), appending the correct error messages as needed. static int get_terminfo_sequence(const wchar_t *seq, wcstring *out_seq, io_streams_t &streams) { if (input_terminfo_get_sequence(seq, out_seq)) { return 1; @@ -380,7 +380,7 @@ static int get_terminfo_sequence(const wchar_t *seq, wcstring *out_seq, io_strea return 0; } -// Add specified key binding. +/// Add specified key binding. static int builtin_bind_add(const wchar_t *seq, const wchar_t *const *cmds, size_t cmds_len, const wchar_t *mode, const wchar_t *sets_mode, int terminfo, io_streams_t &streams) { @@ -399,12 +399,12 @@ static int builtin_bind_add(const wchar_t *seq, const wchar_t *const *cmds, size return 0; } -// Erase specified key bindings -// -// \param seq an array of all key bindings to erase -// \param all if specified, _all_ key bindings will be erased -// \param mode if specified, only bindings from that mode will be erased. If not given and \c all is -// \c false, \c DEFAULT_BIND_MODE will be used. +/// Erase specified key bindings +/// +/// \param seq an array of all key bindings to erase +/// \param all if specified, _all_ key bindings will be erased +/// \param mode if specified, only bindings from that mode will be erased. If not given and \c all +/// is \c false, \c DEFAULT_BIND_MODE will be used. static int builtin_bind_erase(wchar_t **seq, int all, const wchar_t *mode, int use_terminfo, io_streams_t &streams) { if (all) { @@ -439,7 +439,7 @@ static int builtin_bind_erase(wchar_t **seq, int all, const wchar_t *mode, int u } } -// The bind builtin, used for setting character sequences. +/// The bind builtin, used for setting character sequences. static int builtin_bind(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; enum { BIND_INSERT, BIND_ERASE, BIND_KEY_NAMES, BIND_FUNCTION_NAMES }; @@ -594,7 +594,7 @@ static int builtin_bind(parser_t &parser, io_streams_t &streams, wchar_t **argv) return res; } -// The block builtin, used for temporarily blocking events. +/// The block builtin, used for temporarily blocking events. static int builtin_block(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; enum { @@ -699,9 +699,9 @@ static int builtin_block(parser_t &parser, io_streams_t &streams, wchar_t **argv return STATUS_BUILTIN_OK; } -// The builtin builtin, used for giving builtins precedence over functions. Mostly handled by the -// parser. All this code does is some additional operational modes, such as printing a list of all -// builtins, printing help, etc. +/// The builtin builtin, used for giving builtins precedence over functions. Mostly handled by the +/// parser. All this code does is some additional operational modes, such as printing a list of all +/// builtins, printing help, etc. static int builtin_builtin(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int argc = builtin_count_args(argv); int list = 0; @@ -753,7 +753,7 @@ static int builtin_builtin(parser_t &parser, io_streams_t &streams, wchar_t **ar return STATUS_BUILTIN_OK; } -// Implementation of the builtin emit command, used to create events. +/// Implementation of the builtin emit command, used to create events. static int builtin_emit(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; int argc = builtin_count_args(argv); @@ -796,8 +796,8 @@ static int builtin_emit(parser_t &parser, io_streams_t &streams, wchar_t **argv) return STATUS_BUILTIN_OK; } -// Implementation of the builtin 'command'. Actual command running is handled by the parser, this -// just processes the flags. +/// Implementation of the builtin 'command'. Actual command running is handled by the parser, this +/// just processes the flags. static int builtin_command(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; int argc = builtin_count_args(argv); @@ -856,8 +856,8 @@ static int builtin_command(parser_t &parser, io_streams_t &streams, wchar_t **ar return found ? STATUS_BUILTIN_OK : STATUS_BUILTIN_ERROR; } -// A generic bultin that only supports showing a help message. This is only a placeholder that -// prints the help message. Useful for commands that live in the parser. +/// A generic bultin that only supports showing a help message. This is only a placeholder that +/// prints the help message. Useful for commands that live in the parser. static int builtin_generic(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; int argc = builtin_count_args(argv); @@ -898,7 +898,7 @@ static int builtin_generic(parser_t &parser, io_streams_t &streams, wchar_t **ar return STATUS_BUILTIN_ERROR; } -// Return a definition of the specified function. Used by the functions builtin. +/// Return a definition of the specified function. Used by the functions builtin. static wcstring functions_def(const wcstring &name) { CHECK(!name.empty(), L""); wcstring out; @@ -1004,7 +1004,7 @@ static wcstring functions_def(const wcstring &name) { return out; } -// The functions builtin, used for listing and erasing functions. +/// The functions builtin, used for listing and erasing functions. static int builtin_functions(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; int i; @@ -1252,12 +1252,12 @@ static unsigned int builtin_echo_digit(wchar_t wc, unsigned int base) { return UINT_MAX; } -// Parse a numeric escape sequence in str, returning whether we succeeded. Also return the number of -// characters consumed and the resulting value. Supported escape sequences: -// -// \0nnn: octal value, zero to three digits -// \nnn: octal value, one to three digits -// \xhh: hex value, one to two digits +/// Parse a numeric escape sequence in str, returning whether we succeeded. Also return the number +/// of characters consumed and the resulting value. Supported escape sequences: +/// +/// \0nnn: octal value, zero to three digits +/// \nnn: octal value, one to three digits +/// \xhh: hex value, one to two digits static bool builtin_echo_parse_numeric_sequence(const wchar_t *str, size_t *consumed, unsigned char *out_val) { bool success = false; @@ -1299,10 +1299,10 @@ static bool builtin_echo_parse_numeric_sequence(const wchar_t *str, size_t *cons return success; } -// The echo builtin. -// -// Bash only respects -n if it's the first argument. We'll do the same. We also support a new option -// -s to mean "no spaces" +/// The echo builtin. +/// +/// Bash only respects -n if it's the first argument. We'll do the same. We also support a new +/// option -s to mean "no spaces" static int builtin_echo(parser_t &parser, io_streams_t &streams, wchar_t **argv) { /* Skip first arg */ if (!*argv++) return STATUS_BUILTIN_ERROR; @@ -1453,8 +1453,8 @@ static int builtin_echo(parser_t &parser, io_streams_t &streams, wchar_t **argv) return STATUS_BUILTIN_OK; } -// The pwd builtin. We don't respect -P to resolve symbolic links because we -// try to always resolve them. +/// The pwd builtin. We don't respect -P to resolve symbolic links because we +/// try to always resolve them. static int builtin_pwd(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wcstring res = wgetcwd(); if (res.empty()) { @@ -1466,7 +1466,7 @@ static int builtin_pwd(parser_t &parser, io_streams_t &streams, wchar_t **argv) } } -// Adds a function to the function set. It calls into function.cpp to perform any heavy lifting. +/// Adds a function to the function set. It calls into function.cpp to perform any heavy lifting. int define_function(parser_t &parser, io_streams_t &streams, const wcstring_list_t &c_args, const wcstring &contents, int definition_line_offset, wcstring *out_err) { wgetopter_t w; @@ -1811,7 +1811,7 @@ static int builtin_random(parser_t &parser, io_streams_t &streams, wchar_t **arg return STATUS_BUILTIN_OK; } -// The read builtin. Reads from stdin and stores the values in environment variables. +/// The read builtin. Reads from stdin and stores the values in environment variables. static int builtin_read(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; wcstring buff; @@ -2134,7 +2134,7 @@ static int builtin_read(parser_t &parser, io_streams_t &streams, wchar_t **argv) return exit_res; } -// The status builtin. Gives various status information on fish. +/// The status builtin. Gives various status information on fish. static int builtin_status(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; enum { @@ -2304,7 +2304,7 @@ static int builtin_status(parser_t &parser, io_streams_t &streams, wchar_t **arg return res; } -// The exit builtin. Calls reader_exit to exit and returns the value specified. +/// The exit builtin. Calls reader_exit to exit and returns the value specified. static int builtin_exit(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int argc = builtin_count_args(argv); @@ -2337,8 +2337,8 @@ static int builtin_exit(parser_t &parser, io_streams_t &streams, wchar_t **argv) return (int)ec; } -// The cd builtin. Changes the current directory to the one specified or to $HOME if none is -// specified. The directory can be relative to any directory in the CDPATH variable. +/// The cd builtin. Changes the current directory to the one specified or to $HOME if none is +/// specified. The directory can be relative to any directory in the CDPATH variable. static int builtin_cd(parser_t &parser, io_streams_t &streams, wchar_t **argv) { env_var_t dir_in; wcstring dir; @@ -2404,7 +2404,7 @@ static int builtin_cd(parser_t &parser, io_streams_t &streams, wchar_t **argv) { return res; } -// Implementation of the builtin count command, used to count the number of arguments sent to it. +/// Implementation of the builtin count command, used to count the number of arguments sent to it. static int builtin_count(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int argc; argc = builtin_count_args(argv); @@ -2412,8 +2412,8 @@ static int builtin_count(parser_t &parser, io_streams_t &streams, wchar_t **argv return !(argc - 1); } -// Implementation of the builtin contains command, used to check if a specified string is part of a -// list. +/// Implementation of the builtin contains command, used to check if a specified string is part of +/// a list. static int builtin_contains(parser_t &parser, io_streams_t &streams, wchar_t **argv) { wgetopter_t w; int argc; @@ -2473,9 +2473,7 @@ static int builtin_contains(parser_t &parser, io_streams_t &streams, wchar_t **a return 1; } -/** - The . (dot) builtin, sometimes called source. Evaluates the contents of a file. -*/ +/// The . (dot) builtin, sometimes called source. Evaluates the contents of a file. static int builtin_source(parser_t &parser, io_streams_t &streams, wchar_t **argv) { ASSERT_IS_MAIN_THREAD(); int fd; @@ -2539,11 +2537,11 @@ static int builtin_source(parser_t &parser, io_streams_t &streams, wchar_t **arg return res; } -// Make the specified job the first job of the job list. Moving jobs around in the list makes the -// list reflect the order in which the jobs were used. +/// Make the specified job the first job of the job list. Moving jobs around in the list makes the +/// list reflect the order in which the jobs were used. static void make_first(job_t *j) { job_promote(j); } -// Builtin for putting a job in the foreground. +/// Builtin for putting a job in the foreground. static int builtin_fg(parser_t &parser, io_streams_t &streams, wchar_t **argv) { job_t *j = NULL; @@ -2632,7 +2630,7 @@ static int builtin_fg(parser_t &parser, io_streams_t &streams, wchar_t **argv) { return j != 0; } -// Helper function for builtin_bg(). +/// Helper function for builtin_bg(). static int send_to_bg(parser_t &parser, io_streams_t &streams, job_t *j, const wchar_t *name) { if (j == 0) { streams.err.append_format(_(L"%ls: Unknown job '%ls'\n"), L"bg", name); @@ -2654,7 +2652,7 @@ static int send_to_bg(parser_t &parser, io_streams_t &streams, job_t *j, const w return STATUS_BUILTIN_OK; } -// Builtin for putting a job in the background. +/// Builtin for putting a job in the background. static int builtin_bg(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int res = STATUS_BUILTIN_OK; @@ -2700,8 +2698,8 @@ static int builtin_bg(parser_t &parser, io_streams_t &streams, wchar_t **argv) { return res; } -// This function handles both the 'continue' and the 'break' builtins that are used for loop -// control. +/// This function handles both the 'continue' and the 'break' builtins that are used for loop +/// control. static int builtin_break_continue(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int is_break = (wcscmp(argv[0], L"break") == 0); int argc = builtin_count_args(argv); @@ -2740,7 +2738,7 @@ static int builtin_break_continue(parser_t &parser, io_streams_t &streams, wchar return STATUS_BUILTIN_OK; } -// Implementation of the builtin breakpoint command, used to launch the interactive debugger. +/// Implementation of the builtin breakpoint command, used to launch the interactive debugger. static int builtin_breakpoint(parser_t &parser, io_streams_t &streams, wchar_t **argv) { parser.push_block(new breakpoint_block_t()); @@ -2751,7 +2749,7 @@ static int builtin_breakpoint(parser_t &parser, io_streams_t &streams, wchar_t * return proc_get_last_status(); } -// Function for handling the \c return builtin. +/// Function for handling the \c return builtin. static int builtin_return(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int argc = builtin_count_args(argv); int status = proc_get_last_status(); @@ -2801,7 +2799,7 @@ static int builtin_return(parser_t &parser, io_streams_t &streams, wchar_t **arg return status; } -// History of commands executed by user. +/// History of commands executed by user. static int builtin_history(parser_t &parser, io_streams_t &streams, wchar_t **argv) { int argc = builtin_count_args(argv); @@ -3079,7 +3077,7 @@ void builtin_destroy() {} int builtin_exists(const wcstring &cmd) { return !!builtin_lookup(cmd); } -// Return true if the specified builtin should handle it's own help, false otherwise. +/// Return true if the specified builtin should handle it's own help, false otherwise. static int internal_help(const wchar_t *cmd) { CHECK(cmd, 0); return contains(cmd, L"for", L"while", L"function", L"if", L"end", L"switch", L"case", L"count", -- cgit v1.2.3