From 87db9517e928c9007c66ed5b23836db2dad2b693 Mon Sep 17 00:00:00 2001 From: liljencrantz Date: Mon, 14 Jan 2008 02:47:47 +1000 Subject: [PATCH] Add lots of new code comments. darcs-hash:20080113164747-75c98-9d0cefd27be7aef7ba60772616d9da7e6bb52912.gz --- builtin.c | 41 +++++++++++++++++++++++++++++++-- builtin.h | 1 + builtin_commandline.c | 8 +++++++ common.c | 5 +++++ common.h | 15 +++++++++---- complete.h | 32 +++++++++++++------------- env.c | 6 +++++ env_universal_common.c | 19 ++++++++++++---- exec.c | 3 +++ expand.c | 4 +++- fallback.h | 27 ++++++++++++++++++++++ fish.c | 3 +-- fish_indent.c | 24 ++++++++++++++++---- fish_tests.c | 3 +++ function.c | 28 +++++++++++++++-------- function.h | 19 ++++++++++++++++ halloc.c | 6 +++++ history.c | 6 +++++ input.c | 25 ++++++++------------- input.h | 19 +++++++++++----- input_common.c | 2 +- io.h | 3 +++ output.c | 3 +++ output.h | 14 ++++++++++-- path.h | 10 +++++++++ reader.c | 51 +++++++++++++++++++++++++++++++++++++----- screen.c | 7 ++++++ screen.h | 12 ++++++---- util.c | 29 +++++++++++++++++++++--- util.h | 42 +++++++++++++++++++++++++--------- wildcard.c | 26 +++++++++++++++++---- 31 files changed, 399 insertions(+), 94 deletions(-) diff --git a/builtin.c b/builtin.c index 9bf3bd6b6..37b4fadc7 100644 --- a/builtin.c +++ b/builtin.c @@ -407,6 +407,9 @@ static void builtin_missing_argument( const wchar_t *cmd, const wchar_t *opt ) #include "builtin_ulimit.c" #include "builtin_jobs.c" +/** + List all current key bindings + */ static void builtin_bind_list() { array_list_t lst; @@ -442,6 +445,13 @@ static void builtin_bind_list() al_destroy( &lst ); } +/** + 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 ) { array_list_t lst; @@ -460,6 +470,10 @@ static void builtin_bind_key_names( int all ) al_destroy( &lst ); } +/** + Print all the special key binding functions to string buffer used for standard output. + + */ static void builtin_bind_function_names() { array_list_t lst; @@ -478,6 +492,9 @@ static void builtin_bind_function_names() al_destroy( &lst ); } +/** + Add specified key binding. + */ static int builtin_bind_add( wchar_t *seq, wchar_t *cmd, int terminfo ) { @@ -526,6 +543,12 @@ static int builtin_bind_add( wchar_t *seq, wchar_t *cmd, int terminfo ) } +/** + Erase specified key bindings + + \param seq an array of all key bindings to erase + \param all if specified, _all_ key bindings will be erased + */ static void builtin_bind_erase( wchar_t **seq, int all ) { if( all ) @@ -983,7 +1006,9 @@ static int builtin_builtin( wchar_t **argv ) return STATUS_BUILTIN_OK; } - +/** + Implementation of the builtin emit command, used to create events. + */ static int builtin_emit( wchar_t **argv ) { int argc=builtin_count_args( argv ); @@ -2660,7 +2685,10 @@ static int builtin_cd( wchar_t **argv ) return res; } - +/** + Implementation of the builtin count command, used to count the + number of arguments sent to it. + */ static int builtin_count( wchar_t ** argv ) { int argc; @@ -2669,6 +2697,10 @@ static int builtin_count( wchar_t ** argv ) return !(argc-1); } +/** + Implementation of the builtin contains command, used to check if a + specified string is part of a list. + */ static int builtin_contains( wchar_t ** argv ) { int argc; @@ -3408,6 +3440,11 @@ static int builtin_break_continue( wchar_t **argv ) return STATUS_BUILTIN_OK; } +/** + Implementation of the builtin count command, used to launch the + interactive debugger. + */ + static int builtin_breakpoint( wchar_t **argv ) { parser_push_block( BREAKPOINT ); diff --git a/builtin.h b/builtin.h index 3b5d008a5..245fe16c1 100644 --- a/builtin.h +++ b/builtin.h @@ -129,6 +129,7 @@ int builtin_exists( wchar_t *cmd ); of the builtin. The list is terminated by a null pointer. This syntax resembles the syntax for exec. + \param io the io redirections to perform on this builtin. \return the exit status of the builtin command */ diff --git a/builtin_commandline.c b/builtin_commandline.c index 2932d0c3c..db43a18d7 100644 --- a/builtin_commandline.c +++ b/builtin_commandline.c @@ -52,7 +52,15 @@ enum } ; +/** + Pointer to what the commandline builtin considers to be the current + contents of the command line buffer. + */ static wchar_t *current_buffer=0; +/** + What the commandline builtin considers to be the current cursor + position. + */ static int current_cursor_pos = -1; /** diff --git a/common.c b/common.c index 13ec163c2..ed7b92a71 100644 --- a/common.c +++ b/common.c @@ -702,6 +702,11 @@ void write_screen( const wchar_t *msg, string_buffer_t *buff ) sb_append_char( buff, L'\n' ); } +/** + Perform string escaping of a strinng by only quoting it. Assumes + the string has already been checked for characters that can not be + escaped this way. + */ static wchar_t *escape_simple( const wchar_t *in ) { wchar_t *out; diff --git a/common.h b/common.h index e12152019..dd66492d5 100644 --- a/common.h +++ b/common.h @@ -40,11 +40,12 @@ */ #define BYTE_MAX 0xffu -/* - Escape special fish syntax characters liek the semicolon +/** + Escape special fish syntax characters like the semicolon */ #define UNESCAPE_SPECIAL 1 -/* + +/** Allow incomplete escape sequences */ #define UNESCAPE_INCOMPLETE 2 @@ -155,10 +156,16 @@ extern wchar_t *program_name; */ #define N_(wstr) wstr +/** + Check if the specified stringelement is a part of the specified string list + */ #define contains( str,... ) contains_internal( str, __VA_ARGS__, (void *)0 ) +/** + Concatenate all the specified strings into a single newly allocated one + */ #define wcsdupcat( str,... ) wcsdupcat_internal( str, __VA_ARGS__, (void *)0 ) -/* +/** Print a stack trace to stderr */ void show_stackframe(); diff --git a/complete.h b/complete.h index 128db4685..1109da7c1 100644 --- a/complete.h +++ b/complete.h @@ -163,34 +163,34 @@ typedef struct \param comp A space separated list of completions which may contain subshells. \param desc A description of the completion. \param condition a command to be run to check it this completion should be used. If \c condition is empty, the completion is always used. - + \param flags A set of completion flags */ void complete_add( const wchar_t *cmd, - int cmd_type, - wchar_t short_opt, - const wchar_t *long_opt, - int long_mode, - int result_mode, - const wchar_t *condition, - const wchar_t *comp, - const wchar_t *desc, - int flags ); + int cmd_type, + wchar_t short_opt, + const wchar_t *long_opt, + int long_mode, + int result_mode, + const wchar_t *condition, + const wchar_t *comp, + const wchar_t *desc, + int flags ); /** Sets whether the completion list for this command is complete. If true, any options not matching one of the provided options will be flagged as an error by syntax highlighting. */ void complete_set_authoritative( const wchar_t *cmd, - int cmd_type, - int authoritative ); + int cmd_type, + int authoritative ); /** Remove a previously defined completion */ void complete_remove( const wchar_t *cmd, - int cmd_type, - wchar_t short_opt, - const wchar_t *long_opt ); + int cmd_type, + wchar_t short_opt, + const wchar_t *long_opt ); /** Find all completions of the command cmd, insert them into out. The @@ -242,7 +242,7 @@ void complete_load( const wchar_t *cmd, int reload ); Create a new completion entry \param context The halloc context to use for allocating new memory - \pram comp The completion string + \param comp The completion string \param desc The description of the completion \param flags completion flags */ diff --git a/env.c b/env.c index 16b6c0036..c0f1215bd 100644 --- a/env.c +++ b/env.c @@ -480,6 +480,9 @@ static void setup_path() al_destroy( &l ); } +/** + Set up default values for various variables if not defined. + */ static void env_set_defaults() { @@ -1442,6 +1445,9 @@ static void export_func1( void *k, void *v, void *aux ) } +/** + Get list of all exported variables + */ static void get_exported( env_node_t *n, hash_table_t *h ) { if( !n ) diff --git a/env_universal_common.c b/env_universal_common.c index 8c47e3239..bafe25df3 100644 --- a/env_universal_common.c +++ b/env_universal_common.c @@ -99,7 +99,7 @@ var_uni_entry_t; static void parse_message( wchar_t *msg, - connection_t *src ); + connection_t *src ); /** The table of all universal variables @@ -176,8 +176,10 @@ static char *iconv_wide_names_2[]= } ; - -wchar_t *utf2wcs( const char *in ) +/** + Convert utf-8 string to wide string + */ +static wchar_t *utf2wcs( const char *in ) { iconv_t cd=(iconv_t) -1; int i,j; @@ -287,7 +289,10 @@ wchar_t *utf2wcs( const char *in ) return out; } -char *wcs2utf( const wchar_t *in ) +/** + Convert wide string to utf-8 + */ +static char *wcs2utf( const wchar_t *in ) { iconv_t cd=(iconv_t) -1; int i,j; @@ -404,6 +409,9 @@ void env_universal_common_destroy() hash_destroy( &env_universal_var ); } +/** + Read one byte of date form the specified connection + */ static int read_byte( connection_t *src ) { @@ -740,6 +748,9 @@ void try_send_all( connection_t *c ) } } +/** + Escape specified string + */ static wchar_t *full_escape( const wchar_t *in ) { string_buffer_t out; diff --git a/exec.c b/exec.c index f2a771002..7c8948051 100644 --- a/exec.c +++ b/exec.c @@ -830,6 +830,9 @@ static pid_t exec_fork() } +/** + Perform output from builtins + */ static void do_builtin_io( wchar_t *out, wchar_t *err ) { diff --git a/expand.c b/expand.c index 4ec14af3a..069fde748 100644 --- a/expand.c +++ b/expand.c @@ -764,7 +764,9 @@ void expand_variable_error( const wchar_t *token, int token_pos, int error_pos ) } } - +/** + Parse an array slicing specification + */ static int parse_slice( wchar_t *in, wchar_t **end_ptr, array_list_t *idx ) { diff --git a/fallback.h b/fallback.h index 36adc8965..77154ae19 100644 --- a/fallback.h +++ b/fallback.h @@ -54,9 +54,18 @@ typedef char tputs_arg_t; #endif #ifndef HAVE_WINSIZE +/** + Structure used to get the size of a terminal window + */ struct winsize { + /** + Number of rows + */ unsigned short ws_row; + /** + Number of columns + */ unsigned short ws_col; } ; @@ -400,17 +409,35 @@ extern int _nl_msg_cat_cntr; #ifndef HAVE_KILLPG +/** + Send specified signal to specified process group. + */ int killpg( int pgr, int sig ); #endif #ifndef HAVE_WORKING_GETOPT_LONG +/** + Struct describing a long getopt option + */ struct option { + /** + Name of option + */ const char *name; + /** + Flag + */ int has_arg; + /** + Flag + */ int *flag; + /** + Return value + */ int val; } ; diff --git a/fish.c b/fish.c index 9dc97b2dd..435a5c4aa 100644 --- a/fish.c +++ b/fish.c @@ -106,10 +106,9 @@ static int read_init() } -/* +/** Parse the argument list, return the index of the first non-switch arguments. - */ static int fish_parse_opt( int argc, char **argv, char **cmd_ptr ) { diff --git a/fish_indent.c b/fish_indent.c index d3cf9d9f6..3fcb54de3 100644 --- a/fish_indent.c +++ b/fish_indent.c @@ -16,7 +16,7 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/** \file main.c +/** \file fish_indent.c The fish_indent proegram. */ @@ -48,7 +48,10 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #define GETOPT_STRING "hvi" -void read_file( FILE *f, string_buffer_t *b ) +/** + Read the entire contents of a file into the specified string_Buffer_t + */ +static void read_file( FILE *f, string_buffer_t *b ) { while( 1 ) { @@ -62,6 +65,9 @@ void read_file( FILE *f, string_buffer_t *b ) } } +/** + Insert the specified number of tabe into the output buffer + */ static void insert_tabs( string_buffer_t *out, int indent ) { int i; @@ -73,6 +79,9 @@ static void insert_tabs( string_buffer_t *out, int indent ) } +/** + Indent the specified input + */ static int indent( string_buffer_t *out, wchar_t *in, int flags ) { tokenizer tok; @@ -217,7 +226,12 @@ static int indent( string_buffer_t *out, wchar_t *in, int flags ) return res; } -wchar_t *trim( wchar_t *in ) +/** + Remove any prefix and suffix newlines from the specified + string. Does not allocete a new string, edits the string in place + and returns a pointer somewhere into the string. + */ +static wchar_t *trim( wchar_t *in ) { wchar_t *end; @@ -245,7 +259,9 @@ wchar_t *trim( wchar_t *in ) } - +/** + The main mathod. Run the program. + */ int main( int argc, char **argv ) { string_buffer_t sb_in; diff --git a/fish_tests.c b/fish_tests.c index 5a1acfd17..38e4eb105 100644 --- a/fish_tests.c +++ b/fish_tests.c @@ -750,6 +750,9 @@ static void test_expand() } +/** + Test path functions + */ static void test_path() { say( L"Testing path functions" ); diff --git a/function.c b/function.c index 0c9c855b6..830624d39 100644 --- a/function.c +++ b/function.c @@ -41,9 +41,9 @@ typedef struct { /** Function definition */ - wchar_t *cmd; + wchar_t *definition; /** Function description */ - wchar_t *desc; + wchar_t *description; /** File where this function was defined */ @@ -52,7 +52,10 @@ typedef struct Line where definition started */ int definition_offset; - + + /** + List of all named arguments for this function + */ array_list_t *named_arguments; @@ -61,6 +64,10 @@ typedef struct */ int is_autoload; + /** + Set to non-zero if invoking this function shadows the variables + of the underlying function. + */ int shadows; } function_internal_data_t; @@ -155,6 +162,9 @@ void function_init() &hash_wcs_cmp ); } +/** + Clear specified value, but not key + */ static void clear_entry( void *key, void *value ) { halloc_free( value ); @@ -180,7 +190,7 @@ void function_add( function_data_t *data ) d = halloc( 0, sizeof( function_internal_data_t ) ); d->definition_offset = parse_util_lineno( parser_get_buffer(), current_block->tok_pos )-1; - d->cmd = halloc_wcsdup( d, data->definition ); + d->definition = halloc_wcsdup( d, data->definition ); if( data->named_arguments ) { @@ -192,9 +202,9 @@ void function_add( function_data_t *data ) } } - cmd_end = d->cmd + wcslen(d->cmd)-1; + cmd_end = d->definition + wcslen(d->definition)-1; - d->desc = data->description?halloc_wcsdup( d, data->description ):0; + d->description = data->description?halloc_wcsdup( d, data->description ):0; d->definition_file = intern(reader_current_filename()); d->is_autoload = is_autoload; d->shadows = data->shadows; @@ -266,7 +276,7 @@ const wchar_t *function_get_definition( const wchar_t *name ) data = (function_internal_data_t *)hash_get( &function, name ); if( data == 0 ) return 0; - return data->cmd; + return data->definition; } array_list_t *function_get_named_arguments( const wchar_t *name ) @@ -307,7 +317,7 @@ const wchar_t *function_get_desc( const wchar_t *name ) if( data == 0 ) return 0; - return _(data->desc); + return _(data->description); } void function_set_desc( const wchar_t *name, const wchar_t *desc ) @@ -322,7 +332,7 @@ void function_set_desc( const wchar_t *name, const wchar_t *desc ) if( data == 0 ) return; - data->desc = halloc_wcsdup( data, desc ); + data->description = halloc_wcsdup( data, desc ); } /** diff --git a/function.h b/function.h index c4e9030ef..a79b37251 100644 --- a/function.h +++ b/function.h @@ -19,11 +19,30 @@ */ typedef struct function_data { + /** + Name of function + */ wchar_t *name; + /** + Description of function + */ wchar_t *description; + /** + Function definition + */ wchar_t *definition; + /** + List of all event handlers for this function + */ array_list_t *events; + /** + List of all named arguments for this function + */ array_list_t *named_arguments; + /** + Set to non-zero if invoking this function shadows the variables + of the underlying function. + */ int shadows; } function_data_t; diff --git a/halloc.c b/halloc.c index a250c092f..15793990a 100644 --- a/halloc.c +++ b/halloc.c @@ -78,6 +78,9 @@ typedef struct halloc } halloc_t; +/** + Allign the specified pointer + */ static char *align_ptr( char *in ) { unsigned long step = maxi(sizeof(double),sizeof(void *)); @@ -87,6 +90,9 @@ static char *align_ptr( char *in ) return (char *)long_out; } +/** + Allign specifies size_t + */ static size_t align_sz( size_t in ) { size_t step = maxi(sizeof(double),sizeof(void *)); diff --git a/history.c b/history.c index df24ddb2d..4a85ce7e0 100644 --- a/history.c +++ b/history.c @@ -252,6 +252,9 @@ static wchar_t *history_unescape_newlines( wchar_t *in ) return (wchar_t *)out->buff; } +/** + Check if the specified item is already loaded + */ static int item_is_new( history_mode_t *m, void *d ) { char *begin = (char *)d; @@ -409,6 +412,9 @@ static void history_destroy_mode( history_mode_t *m ) } +/** + Free all memory used by specified mistory mode + */ static void history_destroy_mode_wrapper( void *n, history_mode_t *m ) { halloc_free( m ); diff --git a/input.c b/input.c index a45e26fb6..985240ca3 100644 --- a/input.c +++ b/input.c @@ -232,6 +232,9 @@ static const wchar_t code_arr[] = */ static array_list_t mappings = {0,0,0}; +/** + List of all terminfo mappings + */ static array_list_t *terminfo_mappings = 0; @@ -240,28 +243,18 @@ static array_list_t *terminfo_mappings = 0; */ static int is_init = 0; +/** + Initialize terminfo. + */ static void input_terminfo_init(); +/** + Deallocate memory used by terminfo. Or at least try to. Terminfo leaks. + */ static void input_terminfo_destroy(); /** Returns the function description for the given function code. */ -/* -static const wchar_t *input_get_desc( wchar_t c ) -{ - - int i; - for( i = 0; i<(sizeof( code_arr )/sizeof(wchar_t)) ; i++ ) - { - if( c == code_arr[i] ) - { - return desc_arr[i]; - } - } - return 0; -} -*/ - void input_mapping_add( const wchar_t *sequence, const wchar_t *command ) diff --git a/input.h b/input.h index 2814d809f..cd275674f 100644 --- a/input.h +++ b/input.h @@ -89,19 +89,26 @@ void input_unreadch( wint_t ch ); /** - Add a key mapping from the specified sequence + Add a key mapping from the specified sequence to the specified command - \param mode the name of the mapping mode to add this mapping to - \param s the sequence - \param d a description of the sequence - \param cmd an input function that will be run whenever the key sequence occurs + \param sequence the sequence to bind + \param command an input function that will be run whenever the key sequence occurs */ -void input_mapping_add( const wchar_t *sequence, const wchar_t *cmd ); +void input_mapping_add( const wchar_t *sequence, const wchar_t *command ); +/** + Insert all mapping names into the specified array_list_t + */ void input_mapping_get_names( array_list_t *list ); +/** + Erase binding for specified key sequence + */ int input_mapping_erase( const wchar_t *sequence ); +/** + Return the command bound to the specified key sequence + */ const wchar_t *input_mapping_get( const wchar_t *sequence ); /** diff --git a/input_common.c b/input_common.c index 3dd359974..1a2d2d212 100644 --- a/input_common.c +++ b/input_common.c @@ -28,7 +28,7 @@ Implementation file for the low level input library /** Time in milliseconds to wait for another byte to be available for - reading after \x1b is read before assuming that escape key was + reading after \\x1b is read before assuming that escape key was pressed, and not an escape sequence. */ #define WAIT_ON_ESCAPE 10 diff --git a/io.h b/io.h index c670afe05..c2e2d5309 100644 --- a/io.h +++ b/io.h @@ -44,6 +44,9 @@ typedef struct io_data } param2 ; + /** + Set to true if this is an input io redirection + */ int is_input; /** Pointer to the next IO redirection */ diff --git a/output.c b/output.c index 8b5bd418d..eb379337f 100644 --- a/output.c +++ b/output.c @@ -121,6 +121,9 @@ static char *writestr_buff = 0; static int (*out)(char c) = &writeb_internal; +/** + Name of terminal + */ static wchar_t *current_term = 0; diff --git a/output.h b/output.h index 4445b6d5f..0c8faa4b1 100644 --- a/output.h +++ b/output.h @@ -73,7 +73,9 @@ enum void set_color( int c, int c2 ); - +/** + Write specified multibyte string + */ #define writembs( mbs ) \ { \ char *tmp = mbs; \ @@ -144,10 +146,18 @@ int writeb( tputs_arg_t b ); void output_set_writer( int (*writer)(char) ); //typedef int (*func_ptr_t)(char); - +/** + Return the current output writer + */ int (*output_get_writer())(char) ; +/** + Set the terminal name + */ void output_set_term( wchar_t *term ); +/** + Return the terminal name + */ wchar_t *output_get_term(); #endif diff --git a/path.h b/path.h index 19b0756f6..94388f54a 100644 --- a/path.h +++ b/path.h @@ -9,6 +9,9 @@ #ifndef FISH_PATH_H #define FISH_PATH_H +/** + Return value for path_cdpath_get when locatied a rotten symlink + */ #define EROTTEN 1 /** @@ -48,6 +51,13 @@ wchar_t *path_get_path( void *context, const wchar_t *cmd ); */ wchar_t *path_get_cdpath( void *context, wchar_t *in ); +/** + Remove doulbe slashes and trailing slashes from a path, + e.g. transform foo//bar/ into foo/bar. + + The returned string is allocated using the specified halloc + context. + */ wchar_t *path_make_canonical( void *context, const wchar_t *path ); diff --git a/reader.c b/reader.c index 178f0e3c9..8298e14ae 100644 --- a/reader.c +++ b/reader.c @@ -117,6 +117,9 @@ commence. */ #define DEFAULT_PROMPT L"echo \"$USER@\"; hostname|cut -d . -f 1; echo \" \"; pwd; printf '> ';" +/** + The name of the function that prints the fish prompt + */ #define PROMPT_FUNCTION_NAME L"fish_prompt" /** @@ -132,15 +135,40 @@ commence. */ #define READAHEAD_MAX 256 +/** + A mode for calling the reader_kill function. In this mode, the new + string is appended to the current contents of the kill buffer. + */ #define KILL_APPEND 0 +/** + A mode for calling the reader_kill function. In this mode, the new + string is prepended to the current contents of the kill buffer. + */ #define KILL_PREPEND 1 - +/** + History search mode. This value means that no search is currently + performed. + */ #define NO_SEARCH 0 +/** + History search mode. This value means that we are perforing a line + history search. + */ #define LINE_SEARCH 1 +/** + History search mode. This value means that we are perforing a token + history search. + */ #define TOKEN_SEARCH 2 +/** + History search mode. This value means we are searching backwards. + */ #define SEARCH_BACKWARD 0 +/** + History search mode. This value means we are searching forwards. + */ #define SEARCH_FORWARD 1 /** @@ -155,6 +183,9 @@ typedef struct reader_data */ wchar_t *buff; + /** + The representation of the current screen contents + */ screen_t screen; /** @@ -252,6 +283,9 @@ typedef struct reader_data */ int prev_end_loop; + /** + The current contents of the top item in the kill ring. + */ string_buffer_t kill_item; /** @@ -509,6 +543,9 @@ static int check_size() } +/** + Compare two completion entrys + */ static int completion_cmp( const void *a, const void *b ) { completion_t *c= *((completion_t **)a); @@ -518,6 +555,9 @@ static int completion_cmp( const void *a, const void *b ) } +/** + Sort an array_list_t containing compltion_t structs. + */ static void sort_completion_list( array_list_t *comp ) { qsort( comp->arr, @@ -949,9 +989,8 @@ static void get_param( wchar_t *cmd, string. \param val the string to insert - \param is_complete Whether this completion is the whole string or - just the common prefix of several completions. If the former, end by - printing a space (and an end quote if the parameter is quoted). + \param flags A union of all flags describing the completion to insert. See the completion_t struct for more information on possible values. + */ static void completion_insert( const wchar_t *val, int flags ) { @@ -1225,7 +1264,7 @@ static void run_pager( wchar_t *prefix, int is_quoted, array_list_t *comp ) io_buffer_destroy( in); } -/* +/** Flash the screen. This function only changed the color of the current line, since the flash_screen sequnce is rather painful to look at in most terminal emulators. @@ -1801,7 +1840,7 @@ static void handle_token_history( int forward, int reset ) \param dir Direction to move/erase. 0 means move left, 1 means move right. \param erase Whether to erase the characters along the way or only move past them. - \param do_append if erase is true, this flag decides if the new kill item should be appended to the previous kill item. + \param new if the new kill item should be appended to the previous kill item or not. */ static void move_word( int dir, int erase, int new ) { diff --git a/screen.c b/screen.c index 5ca09f5bf..949eac450 100644 --- a/screen.c +++ b/screen.c @@ -86,6 +86,10 @@ static int try_sequence( char *seq, wchar_t *str ) return 0; } +/** + Returns the number of columns left until the next tab stop, given + the current cursor postion. + */ static int next_tab_stop( int in ) { /* @@ -759,6 +763,9 @@ static void s_update( screen_t *scr, wchar_t *prompt ) } +/** + Returns non-zero if we are using a dumb terminal. + */ static int is_dumb() { return ( !cursor_up || !cursor_down || !cursor_left || !cursor_right ); diff --git a/screen.h b/screen.h index 19b12f7f2..0e2c798a3 100644 --- a/screen.h +++ b/screen.h @@ -2,9 +2,13 @@ The screen library allows the interactive reader to write its output to screen efficiently by keeping an inetrnal representation - of the current screen contents and trying to find the most + of the current screen contents and trying to find a reasonably efficient way for transforming that to the desired screen content. -*/ + + The current implementation is less smart than ncurses allows + and can not for example move blocks of text around to handle text + insertion. + */ #ifndef FISH_SCREEN_H #define FISH_SCREEN_H @@ -13,7 +17,7 @@ */ typedef struct { - /* + /** The internal representation of the desired screen contents. */ array_list_t desired; @@ -35,7 +39,7 @@ typedef struct */ string_buffer_t actual_prompt; - /* + /** The actual width of the screen at the time of the last screen write. */ diff --git a/util.c b/util.c index c2e435d3a..cf776eb2d 100644 --- a/util.c +++ b/util.c @@ -50,6 +50,10 @@ */ #define SB_MAX_SIZE 32767 +/** + Handle oom condition. Default action is to print a stack trace and + exit, but an alternative action can be specified. + */ #define oom_handler( p ) \ { \ if( oom_handler_internal == util_die_on_oom ) \ @@ -77,7 +81,7 @@ void (*util_set_oom_handler( void (*h)(void *) ))(void *) return old; } -void util_die_on_oom( void * p) +void util_die_on_oom( void *p ) { } @@ -790,6 +794,10 @@ void al_destroy( array_list_t *l ) free( l->arr ); } +/** + Real implementation of all al_push_* versions. Pushes arbitrary + element to end of list. + */ static int al_push_generic( array_list_t *l, anything_t o ) { if( l->pos >= l->size ) @@ -887,6 +895,10 @@ int al_insert( array_list_t *a, int pos, int count ) return 1; } +/** + Real implementation of all al_set_* versions. Sets arbitrary + element of list. + */ static int al_set_generic( array_list_t *l, int pos, anything_t v ) { @@ -926,13 +938,16 @@ int al_set_long( array_list_t *l, int pos, long o ) return al_set_generic( l, pos, v ); } -int al_set_func( array_list_t *l, int pos, func_ptr_t o ) +int al_set_func( array_list_t *l, int pos, func_ptr_t f ) { anything_t v; - v.func_val = o; + v.func_val = f; return al_set_generic( l, pos, v ); } +/** + Real implementation of all al_get_* versions. Returns element from list. + */ static anything_t al_get_generic( array_list_t *l, int pos ) { anything_t res; @@ -967,6 +982,10 @@ void al_truncate( array_list_t *l, int new_sz ) l->pos = new_sz; } +/** + Real implementation of all al_pop_* versions. Pops arbitrary + element from end of list. + */ static anything_t al_pop_generic( array_list_t *l ) { anything_t e; @@ -1014,6 +1033,10 @@ func_ptr_t al_pop_func( array_list_t *l ) return al_pop_generic(l).func_val; } +/** + Real implementation of all al_peek_* versions. Peeks last element + of list. + */ static anything_t al_peek_generic( array_list_t *l ) { anything_t res; diff --git a/util.h b/util.h index 7d83d0011..84bbe0970 100644 --- a/util.h +++ b/util.h @@ -15,12 +15,29 @@ #include #include +/** + Typedef for a generic function pointer + */ typedef void (*func_ptr_t)(); +/** + A union of all types that can be stored in an array_list_t. This is + used to make sure that the pointer type can fit whatever we want to + insert. + */ typedef union { + /** + long value + */ long long_val; + /** + pointer value + */ void *ptr_val; + /** + function pointer value + */ func_ptr_t func_val; } anything_t; @@ -163,7 +180,7 @@ buffer_t; typedef buffer_t string_buffer_t; /** - Set the out of memory handler callback function. If a memory + Set the out-of-memory handler callback function. If a memory allocation fails, this function will be called. */ void (*util_set_oom_handler( void (*h)(void *) ))(void *); @@ -175,7 +192,7 @@ void (*util_set_oom_handler( void (*h)(void *) ))(void *); This is the default out of memory handler. */ -void util_die_on_oom( void * ); +void util_die_on_oom( void *p ); /** Returns the larger of two ints @@ -428,11 +445,10 @@ int al_push_long( array_list_t *l, long o ); Append element to list \param l The list - \param o The element - \return + \param f The element \return 1 if succesfull, 0 otherwise */ -int al_push_func( array_list_t *l, void (*f)() ); +int al_push_func( array_list_t *l, func_ptr_t f ); /** Append all elements of a list to another @@ -443,6 +459,9 @@ int al_push_func( array_list_t *l, void (*f)() ); */ int al_push_all( array_list_t *a, array_list_t *b ); +/** + Insert the specified number of new empty positions at the specified position in the list. + */ int al_insert( array_list_t *a, int pos, int count ); /** @@ -458,7 +477,7 @@ int al_set( array_list_t *l, int pos, const void *o ); \param l The array_list_t \param pos The index - \param o The element + \param v The element to set */ int al_set_long( array_list_t *l, int pos, long v ); /** @@ -466,9 +485,9 @@ int al_set_long( array_list_t *l, int pos, long v ); \param l The array_list_t \param pos The index - \param o The element + \param f The element to insert */ -int al_set_func( array_list_t *l, int pos, void (*f)() ); +int al_set_func( array_list_t *l, int pos, func_ptr_t f ); /** Returns the element at the specified index @@ -599,15 +618,18 @@ void sb_init( string_buffer_t * ); string_buffer_t *sb_new(); /** - Append a part of a string to the buffer + Append a part of a string to the buffer. */ void sb_append_substring( string_buffer_t *, const wchar_t *, size_t ); /** - Append a character to the buffer + Append a character to the buffer. */ void sb_append_char( string_buffer_t *, wchar_t ); +/** + Append all specified items to buffer. + */ #define sb_append( sb,... ) sb_append_internal( sb, __VA_ARGS__, (void *)0 ) /** diff --git a/wildcard.c b/wildcard.c index 9456b85f7..f585dbb98 100644 --- a/wildcard.c +++ b/wildcard.c @@ -378,7 +378,11 @@ static wchar_t *make_path( const wchar_t *base_dir, const wchar_t *name ) return long_name; } - +/** + Return a description of a file based on its suffix. This function + does not perform any caching, it directly calls the mimedb command + to do a lookup. + */ static wchar_t *complete_get_desc_suffix_internal( const wchar_t *suff_orig ) { @@ -425,15 +429,22 @@ static wchar_t *complete_get_desc_suffix_internal( const wchar_t *suff_orig ) return desc; } +/** + Free the suffix_hash hash table and all memory used by it. + */ static void complete_get_desc_destroy_suffix_hash() { - hash_foreach( suffix_hash, &clear_hash_entry ); - hash_destroy( suffix_hash ); - free( suffix_hash ); + if( suffix_hash ) + { + hash_foreach( suffix_hash, &clear_hash_entry ); + hash_destroy( suffix_hash ); + free( suffix_hash ); + } } + /** Use the mimedb command to look up a description for a given suffix */ @@ -759,7 +770,14 @@ static int test_flags( wchar_t *filename, return 1; } +/** + The real implementation of wildcard expansion is in this + function. Other functions are just wrappers around this one. + This function traverses the relevant directory tree looking for + matches, and recurses when needed to handle wildcrards spanning + multiple components and recursive wildcards. + */ static int wildcard_expand_internal( const wchar_t *wc, const wchar_t *base_dir, int flags,