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 );