Large number of sourcecode comment edits, and some minor code polish

darcs-hash:20060620005010-ac50b-eaeae9a6242a37c1e34831e1a0b2ee2b4e7a012e.gz

expand.c

@@ -570,6 +570,13 @@ static int expand_pid( wchar_t *in,
 					   int flags,
 					   array_list_t *out )
 {
+
+	if( !in || !out)
+	{
+		debug( 2, L"Got null string on line %d of file %s", __LINE__, __FILE__ );
+		return 0;		
+	}
+
 	if( *in != PROCESS_EXPAND )
 	{
 		al_push( out, in );
@@ -663,6 +670,12 @@ static int expand_variables( wchar_t *in, array_list_t *out, int last_idx )
 	static string_buffer_t *var_tmp = 0;
 	static array_list_t *var_idx_list = 0;
 
+	if( !in || !out)
+	{
+		debug( 2, L"Got null string on line %d of file %s", __LINE__, __FILE__ );
+		return 0;		
+	}
+
 	if( !var_tmp )
 	{
 		var_tmp = sb_halloc( global_context );
@@ -986,6 +999,12 @@ static int expand_brackets( wchar_t *in, int flags, array_list_t *out )
 	wchar_t *item_begin;
 	int len1, len2, tot_len;
 	
+	if( !in || !out)
+	{
+		debug( 2, L"Got null string on line %d of file %s", __LINE__, __FILE__ );
+		return 0;		
+	}
+
 	for( pos=in;
 		 (*pos) && !syntax_error;
 		 pos++ )
@@ -1116,18 +1135,12 @@ static int expand_subshell( wchar_t *in, array_list_t *out )
 	int i, j;
 	const wchar_t *item_begin;
 
-	if( !in )
+	if( !in || !out)
 	{
 		debug( 2, L"Got null string on line %d of file %s", __LINE__, __FILE__ );
 		return 0;		
 	}
 
-	if( !out )
-	{
-		debug( 2, L"Got null pointer on line %d of file %s", __LINE__, __FILE__ );
-		return 0;		
-	}
-
 	switch( parse_util_locate_cmdsubst(in,
 									   &paran_begin,
 									   &paran_end,
@@ -1209,7 +1222,9 @@ static int expand_subshell( wchar_t *in, array_list_t *out )
 	return 1;
 }
 
-
+/**
+   Wrapper around unescape funtion. Issues an error() on failiure.
+*/
 static wchar_t *expand_unescape( const wchar_t * in, int escape_special )
 {
 	wchar_t *res = unescape( in, escape_special );

expand.h

@@ -132,6 +132,9 @@ enum
 */
 #define COMPLETE_VAR_PARAN_DESC _( L"Did you mean (COMMAND)? In fish, the '$' character is only used for accessing variables. To learn more about command substitution in fish, type 'help expand-command-substitution'.")
 
+/**
+   Error issued on array out of bounds
+*/
 #define ARRAY_BOUNDS_ERR _(L"Array index out of bounds")
 
 

fallback.h

@@ -310,8 +310,9 @@ struct drand48_data
    Fallback implementation of lrand48_r. Internally uses rand_r, so it is pretty weak.
 */
 int lrand48_r(struct drand48_data *buffer, long int *result);
+
 /**
-   Fallback implementation of srand48_r
+   Fallback implementation of srand48_r, the seed function for lrand48_r.
 */
 int srand48_r(long int seedval, struct drand48_data *buffer);
 

fish_tests.c

@@ -51,6 +51,11 @@
 */
 #define LAPS 50
 
+/**
+   The result of one of the test passes
+*/
+#define NUM_ANS L"-7 99999999 1234567 deadbeef DEADBEEFDEADBEEF"
+
 /**
    Number of encountered errors
 */
@@ -345,8 +350,6 @@ static void sb_test()
 
 	sb_clear( &b );
 
-#define NUM_ANS L"-7 99999999 1234567 deadbeef DEADBEEFDEADBEEF"
-
 	sb_printf( &b, L"%d %u %o %x %llX", -7, 99999999, 01234567, 0xdeadbeef, 0xdeadbeefdeadbeefll );
 	if( wcscmp( (wchar_t *)b.buff,  NUM_ANS) != 0 )
 	{

fishd.c

@@ -6,7 +6,7 @@ variables from ~/.fishd, and takes care of communication between fish
 instances. When no clients are running, fishd will automatically shut
 down and save.
 
-\subsection fishd-commands Commands
+\section fishd-commands Commands
 
 Fishd works by sending and receiving commands. Each command is ended
 with a newline. These are the commands supported by fishd:
@@ -90,6 +90,9 @@ time the original barrier request was sent have been received.
 */
 #define GREETING "# Fish universal variable daemon\n"
 
+/**
+   Small not about not editing ~/.fishd manually. Inserted at the top of all .fishd files.
+*/
 #define SAVE_MSG "# This file is automatically generated by the fishd universal variable daemon.\n# Do NOT edit it directly, your changes will be overwritten.\n"
 
 /**

function.c

@@ -306,6 +306,9 @@ void function_set_desc( const wchar_t *name, const wchar_t *desc )
 	data->desc =wcsdup(desc);
 }
 
+/**
+   Search arraylist of strings for specified string
+*/
 static int al_contains_str( array_list_t *list, const wchar_t * str )
 {
 	int i;

halloc.c

@@ -18,37 +18,92 @@
 #include "common.h"
 #include "halloc.h"
 
+/**
+   Extra size to allocate whenever doing a halloc, in order to fill uyp smaller halloc calls
+*/
 #define HALLOC_BLOCK_SIZE 128
+
+/**
+   Maximum size of trailing halloc space to refuse to discard
+*/
 #define HALLOC_SCRAP_SIZE 16
 
 #ifdef HALLOC_DEBUG
+/**
+   Debug statistic parameter
+*/
 static int child_count=0;
+/**
+   Debug statistic parameter
+*/
 static int child_size=0;
+/**
+   Debug statistic parameter
+*/
 static int alloc_count =0;
+/**
+   Debug statistic parameter
+*/
 static int alloc_spill = 0;
+/**
+   Debug statistic parameter
+*/
 static pid_t pid=0;
+/**
+   Debug statistic parameter
+*/
 static int parent_count=0;
 #endif
 
+/**
+   The main datastructure for a main halloc context
+*/
 typedef struct halloc
 {
+	/**
+	   List of all addresses and functions to call on them
+	*/
 	array_list_t children;
+	/**
+	   Memory scratch area used to fullfil smaller memory allocations
+	*/
 	void *scratch;
+	/**
+	   Amount of free space in the scratch area
+	*/
 	size_t scratch_free;
-	long long data[0];
+#if __STDC_VERSION__ < 199901L
+	/**
+	   The actual data. MAde to be of type long long to make sure memory alignment is in order.
+	*/
+	long long data[1]; // Waste one byte on non-C99 compilers... :-( 
+#else
+	long long data[];
+#endif
 }
 	halloc_t;
 
+/**
+   Get the offset of the halloc structure before a data block
+*/
 static halloc_t *halloc_from_data( void *data )
 {
 	return (halloc_t *)(((char *)data) - sizeof( halloc_t ) );
 }
 
+/**
+   A function that does nothing
+*/
 static void late_free( void *data)
 {
 }
 
 #ifdef HALLOC_DEBUG
+/**
+   Debug function, called at exit when in debug mode. Prints usage
+   statistics, like number of allocations and number of internal calls
+   to malloc.
+*/
 static void woot()
 {
 	if( getpid() == pid )

halloc_util.c

@@ -51,6 +51,9 @@ string_buffer_t *sb_halloc( void *context )
 	return res;
 }
 
+/**
+   A function that takes a single parameter, which is a function pointer, and calls it.
+*/
 static void halloc_passthrough( void *f )
 {
 	void (*func)() = (void (*)() )f;

highlight.c

@@ -33,6 +33,9 @@
 #include "halloc.h"
 #include "halloc_util.h"
 
+/**
+   Number of elements in the highlight_var array
+*/
 #define VAR_COUNT ( sizeof(highlight_var)/sizeof(wchar_t *) )
 
 static void highlight_universal_internal( wchar_t * buff, 
@@ -62,6 +65,11 @@ static wchar_t *highlight_var[] =
 }
 	;
 
+/**
+   Tests if the specified string is the prefix of any valid path in the system. 
+
+   \return zero it this is not a valid prefix, non-zero otherwise
+*/
 static int is_potential_path( const wchar_t *path )
 {
 	wchar_t *tilde, *unescaped;

highlight.h

@@ -9,6 +9,59 @@
 
 #include "util.h"
 
+/**
+   Internal value representing highlighting of normal text
+*/
+#define HIGHLIGHT_NORMAL 0x1
+/**
+   Internal value representing highlighting of an error
+*/
+#define HIGHLIGHT_ERROR 0x2
+/**
+   Internal value representing highlighting of a command
+*/
+#define HIGHLIGHT_COMMAND 0x4
+/**
+   Internal value representing highlighting of a process separator
+*/
+#define HIGHLIGHT_END 0x8
+/**
+   Internal value representing highlighting of a regular command parameter
+*/
+#define HIGHLIGHT_PARAM 0x10
+/**
+   Internal value representing highlighting of a comment
+*/
+#define HIGHLIGHT_COMMENT 0x20
+/**
+   Internal value representing highlighting of a matching parenteses, etc.
+*/
+#define HIGHLIGHT_MATCH 0x40
+/**
+   Internal value representing highlighting of a search match
+*/
+#define HIGHLIGHT_SEARCH_MATCH 0x80
+/**
+   Internal value representing highlighting of an operator
+*/
+#define HIGHLIGHT_OPERATOR 0x100
+/**
+   Internal value representing highlighting of an escape sequence
+*/
+#define HIGHLIGHT_ESCAPE 0x200
+/**
+   Internal value representing highlighting of a quoted string
+*/
+#define HIGHLIGHT_QUOTE 0x400
+/**
+   Internal value representing highlighting of an IO redirection
+*/
+#define HIGHLIGHT_REDIRECTION 0x800 
+/**
+   Internal value representing highlighting a potentially valid path
+*/
+#define HIGHLIGHT_VALID_PATH 0x1000
+
 /**
    Perform syntax highlighting for the shell commands in buff. The result is
    stored in the color array as a color_code from the HIGHLIGHT_ enum

input.c

@@ -232,6 +232,9 @@ static int inputrc_block_count=0;
 */
 static int inputrc_error = 0;
 
+/**
+   Set to one when the input subsytem has been initialized. 
+*/
 static int is_init = 0;
 
 wchar_t input_get_code( wchar_t *name )

io.h

@@ -89,6 +89,9 @@ io_data_t *io_buffer_create();
 */
 void io_buffer_read( io_data_t *d );
 
+/**
+   Print debug information about the specified IO redirection chain to stderr.
+*/
 void io_print( io_data_t *io );
 
 #endif

output.c

@@ -113,6 +113,9 @@ static char *writestr_buff = 0;
 
 static int (*out)(char c) = &writeb_internal;
 
+/**
+   Cleanup function. Run automatically through halloc
+*/
 static void output_destroy()
 {
 	free( writestr_buff );
@@ -347,6 +350,9 @@ void move_cursor( int steps )
 	}
 }
 
+/**
+   Default output method, simply calls write() on stdout
+*/
 static int writeb_internal( char c )
 {
 	write( 1, &c, 1 );

output.h

@@ -10,20 +10,6 @@
 
 #include <wchar.h>
 
-#define HIGHLIGHT_NORMAL 0x1
-#define HIGHLIGHT_ERROR 0x2
-#define HIGHLIGHT_COMMAND 0x4
-#define HIGHLIGHT_END 0x8
-#define HIGHLIGHT_PARAM 0x10
-#define HIGHLIGHT_COMMENT 0x20
-#define HIGHLIGHT_MATCH 0x40
-#define HIGHLIGHT_SEARCH_MATCH 0x80
-#define HIGHLIGHT_OPERATOR 0x100
-#define HIGHLIGHT_ESCAPE 0x200
-#define HIGHLIGHT_QUOTE 0x400
-#define HIGHLIGHT_REDIRECTION 0x800 
-#define HIGHLIGHT_VALID_PATH 0x1000
-
 /**
    Constants for various colors as used by the set_color function. 
 */
@@ -44,7 +30,13 @@ enum
 }
 ;
 
+/**
+   The value to send to set_color to tell it to use a bold font
+*/
 #define FISH_COLOR_BOLD 0x80
+/**
+   The value to send to set_color to tell it to underline the text
+*/
 #define FISH_COLOR_UNDERLINE 0x100
 
 /**

parse_util.h

@@ -22,7 +22,7 @@
 int parse_util_locate_cmdsubst( const wchar_t *in, 
 								wchar_t **begin, 
 								wchar_t **end,
-								int allow_incomplete );
+								int flags );
 
 /**
    Find the beginning and end of the command substitution under the cursor
@@ -65,12 +65,16 @@ void parse_util_job_extent( const wchar_t *buff,
 							wchar_t **b );
 
 /**
-   Find the beginning and end of the token under the cursor
+   Find the beginning and end of the token under the cursor and the
+   toekn before the current token. Any combination of tok_begin,
+   tok_end, prev_begin and prev_end may be null.
 
    \param buff the string to search for subshells
    \param cursor_pos the position of the cursor
-   \param a the start of the searched string
-   \param b the end of the searched string
+   \param tok_begin the start of the current token
+   \param tok_end the end of the current token
+   \param prev_begin the start o the token before the current token
+   \param prev_end the end of the token before the current token
 */
 void parse_util_token_extent( const wchar_t *buff,
 							  int cursor_pos,

parser.c

@@ -969,7 +969,10 @@ void parser_destroy()
 }
 
 /**
-   Print error message if an error has occured while parsing
+   Print error message to string_buffer_t if an error has occured while parsing
+
+   \param target the buffer to write to
+   \param prefix: The string token to prefix the ech line with. Usually the name of the command trying to parse something.
 */
 static void print_errors( string_buffer_t *target, const wchar_t *prefix )
 {
@@ -988,6 +991,9 @@ static void print_errors( string_buffer_t *target, const wchar_t *prefix )
 	}
 }
 
+/**
+   Print error message to stderr if an error has occured while parsing
+*/
 static void print_errors_stderr()
 {
 	if( error_code )

proc.c

@@ -108,6 +108,9 @@ static string_buffer_t event_pid;
 */
 static string_buffer_t event_status;
 
+/**
+   A stack containing the values of is_interactive. Used by proc_push_interactive and proc_pop_interactive.
+*/
 static array_list_t *interactive_stack;
 
 void proc_init()

signal.c

@@ -46,6 +46,9 @@ struct lookup_entry
 	const wchar_t *desc;	
 };
 
+/**
+   The number of signal blocks in place. Increased by signal_block, decreased by signal_unblock.
+*/
 static int block_count=0;
 
 
@@ -53,7 +56,7 @@ static int block_count=0;
    Lookup table used to convert between signal names and signal ids,
    etc.
 */
-static struct lookup_entry lookup[] =
+const static struct lookup_entry lookup[] =
 {
 #ifdef SIGHUP
 	{

translate.c

@@ -47,8 +47,14 @@ static char *wcs2str_buff=0;
 */
 static size_t wcs2str_buff_count=0;
 
+/**
+   Flag to tell whether the translation library has been initialized
+*/
 static int is_init = 0;
 
+/**
+   Internal shutdown function. Automatically called on shutdown if the library has been initialized.
+*/
 static void internal_destroy()
 {
 	int i;
@@ -64,6 +70,9 @@ static void internal_destroy()
 	free( wcs2str_buff );
 }
 
+/**
+   Internal init function. Automatically called when a translation is first requested.
+*/
 static void internal_init()
 {
 	int i;

util.h

@@ -536,7 +536,7 @@ int sb_vprintf( string_buffer_t *buffer, const wchar_t *format, va_list va_orig
 void sb_destroy( string_buffer_t * );
 
 /**
-   Truncate the buffer. This will not deallocate the memory used, it will only set the contents of the string to L"\0".
+   Truncate the buffer. This will not deallocate the memory used, it will only set the contents of the string to L"\\0".
 */
 void sb_clear( string_buffer_t * );
 

wildcard.c

@@ -303,7 +303,10 @@ static wchar_t *make_path( const wchar_t *base_dir, const wchar_t *name )
 	return long_name;
 }
 
-void get_desc( wchar_t *fn, string_buffer_t *sb, int is_cmd )
+/**
+   Get the description of the specified filename. If this is a regular file, append the filesize to the description.
+*/
+static void get_desc( wchar_t *fn, string_buffer_t *sb, int is_cmd )
 {
 	const wchar_t *desc;
 	
@@ -376,7 +379,7 @@ void get_desc( wchar_t *fn, string_buffer_t *sb, int is_cmd )
 	}
 }
 
-/*
+/**
   Test if the file specified by the given filename matches the
   expansion flags specified. flags can be a combination of
   EXECUTABLES_ONLY and DIRECTORIES_ONLY.

wutil.c

@@ -29,12 +29,18 @@
 #include "halloc.h"
 #include "halloc_util.h"
 
+/**
+   Minimum length of the internal covnersion buffers
+*/
 #define TMP_LEN_MIN 256
 
 #ifndef PATH_MAX
 #ifdef MAXPATHLEN
 #define PATH_MAX MAXPATHLEN
 #else
+/**
+   Fallback length of MAXPATHLEN. Just a hopefully sane value...
+*/
 #define PATH_MAX 4096
 #endif
 #endif
@@ -44,11 +50,20 @@
    the \c wutil_wcs2str() function.
 */
 static char *tmp=0;
+/**
+   Buffer for converting narrow results to wide ones, used by the \c
+   wutil_str2wcs() function. Avoid usign this without thinking about
+   it, since sebseuent calls will overwrite previous values.
+*/
 static wchar_t *tmp2;
 /**
    Length of the \c tmp buffer.
 */
 static size_t tmp_len=0;
+
+/**
+   Length of the \c tmp2 buffer
+*/
 static size_t tmp2_len;
 
 /**
@@ -56,6 +71,9 @@ static size_t tmp2_len;
 */
 static int wutil_calls = 0;
 
+/**
+   Storage for the wreaddir function
+*/
 static struct wdirent my_wdirent;
 
 void wutil_init()