Huge API documentation cleanup

darcs-hash:20051024152625-ac50b-41503feb4ea8d428c5b30c159aaae0c8f7ae46a2.gz

builtin.c

@@ -724,6 +724,9 @@ static int wcsbindingname( wchar_t *str )
 	return 1;
 }
 
+/**
+   Debug function to print the current block stack
+*/
 static void print_block_stack( block_t *b )
 {
 	if( !b )
@@ -1414,6 +1417,9 @@ static int builtin_read( wchar_t **argv )
 	return 0;
 }
 
+/**
+   The status builtin. Gives various status information on fish.
+*/
 static int builtin_status( wchar_t **argv )
 {
 	enum 
@@ -2458,6 +2464,9 @@ static int builtin_for( wchar_t **argv )
 	return res;
 }
 
+/**
+   The begin builtin. Creates a nex block.
+*/
 static int builtin_begin( wchar_t **argv )
 {
 	parser_push_block( BEGIN );

builtin.h

@@ -17,10 +17,29 @@ enum
 }
 ;
 
+/**
+   Error message on missing argument
+*/
 #define BUILTIN_ERR_MISSING L": Expected argument"
+
+/**
+   Error message on invalid combination of options
+*/
 #define BUILTIN_ERR_COMBO L": Invalid combination of options"
+
+/**
+   Error message on multiple scope levels for variables
+*/
 #define BUILTIN_ERR_GLOCAL L": Variable can only be one of universal, global and local"
+
+/**
+   Error message for specifying both export and unexport to set/read
+*/
 #define BUILTIN_ERR_EXPUNEXP L": Variable can't be both exported and unexported"
+
+/**
+   Error message for unknown switch
+*/
 #define BUILTIN_ERR_UNKNOWN	L": Unknown option"
 
 /**
@@ -103,8 +122,19 @@ int builtin_count_args( wchar_t **argv );
 void builtin_print_help( wchar_t *cmd, string_buffer_t *b );
 
 
+/**
+   The set builtin, used for setting variables. Defined in builtin_set.c.
+*/
 int builtin_set(wchar_t **argv);
+
+/**
+   The commandline builtin, used for setting and getting the contents of the commandline. Defined in builtin_commandline.c.
+*/
 int builtin_commandline(wchar_t **argv);
+
+/**
+   The ulimit builtin, used for setting resource limits. Defined in builtin_ulimit.c.
+*/
 int builtin_ulimit(wchar_t **argv);
 
 /** 

builtin_commandline.c

@@ -47,6 +47,14 @@ enum
 	;
 
 
+/**
+   Replace/append/insert the selection with/at/after the specified string.
+
+   \param begin beginning of selection
+   \param end end of selection
+   \param insert the string to insert
+   \param append_mode can be one of REPLACE_MODE, INSERT_MODE or APPEND_MODE, affects the way the test update is performed
+*/
 static void replace_part( wchar_t *begin,
 						  wchar_t *end,
 						  wchar_t *insert,
@@ -95,10 +103,18 @@ static void replace_part( wchar_t *begin,
 	sb_destroy( &out );
 }
 	
-void write_part( wchar_t *begin, 
+/**
-				 wchar_t *end, 
+   Output the specified selection.
-				 int cut_at_cursor, 
+
-				 int tokenize )
+   \param begin start of selection
+   \param end  end of selection
+   \param cut_at_cursor whether printing should stop at the surrent cursor position
+   \param tokenize whether the string should be tokenized, printing one string token on every line and skipping non-string tokens
+*/
+static void write_part( wchar_t *begin, 
+						wchar_t *end, 
+						int cut_at_cursor, 
+						int tokenize )
 {	
 	tokenizer tok;
 	string_buffer_t out;

builtin_ulimit.c

@@ -1,6 +1,6 @@
-/** \file builtin_commandline.c Functions defining the commandline builtin
+/** \file builtin_ulimit.c Functions defining the ulimit builtin
 
-Functions used for implementing the commandline builtin. 
+Functions used for implementing the ulimit builtin. 
 
 */
 #include <stdlib.h>
@@ -18,14 +18,29 @@ Functions used for implementing the commandline builtin.
 #include "common.h"
 #include "wgetopt.h"
 
+/**
+   Struct describing a resource limit
+*/
 struct resource_t
 {
+	/**
+	   Resource id
+	 */
 	int resource;
+	/**
+	   Description of resource
+	*/
 	const wchar_t *desc;
+	/**
+	   Switch used on commandline to specify resource
+	*/
 	wchar_t switch_char;	
 }
 	;
 
+/**
+   Array of resource_t structs, describing all known resource types.
+*/
 const static struct resource_t resource_arr[] =
 {
 	{
@@ -76,6 +91,9 @@ const static struct resource_t resource_arr[] =
 }
 	;
 
+/**
+   Get the implicit multiplication factor for the specified resource limit
+*/
 static int get_multiplier( int what )
 {
 	if( ( what == RLIMIT_NPROC ) || 
@@ -87,7 +105,9 @@ static int get_multiplier( int what )
 	return 1024;
 }
 
-
+/**
+   Return the value for the specified resource limit
+*/
 static rlim_t get( int resource, int hard )
 {
 	struct rlimit ls;
@@ -97,6 +117,9 @@ static rlim_t get( int resource, int hard )
 	return hard ? ls.rlim_max:ls.rlim_cur;
 }
 
+/**
+   Print the value of the specified resource limit
+*/
 static void print( int resource, int hard )
 {
 	rlim_t l = get( resource, hard );
@@ -108,7 +131,9 @@ static void print( int resource, int hard )
 	
 }
 
-
+/**
+   Print values of all resource limits
+*/
 static void print_all( int hard )
 {
 	int i;
@@ -142,6 +167,9 @@ static void print_all( int hard )
 	}
 }
 
+/**
+   Returns the description for the specified resource limit
+*/
 static const wchar_t *get_desc( int what )
 {
 	int i;
@@ -156,7 +184,9 @@ static const wchar_t *get_desc( int what )
 	return L"Not a resource";
 }
 
-
+/**
+   Set the new value of the specified resource limit
+*/
 static int set( int resource, int hard, int soft, rlim_t value )
 {
 	struct rlimit ls;
@@ -194,6 +224,9 @@ static int set( int resource, int hard, int soft, rlim_t value )
 	return 0;	
 }
 
+/**
+   Set all resource limits
+*/
 static int set_all( int hard, int soft, rlim_t value )
 {
 	int i;

common.c

@@ -26,6 +26,11 @@ parts of fish.
 #include <fcntl.h>
 
 #ifndef HOST_NAME_MAX
+/**
+   Maximum length of hostname return. It is ok if this is too short,
+   getting the actual hostname is not critical, so long as the string
+   is unique in the filesystem namespace.
+*/
 #define HOST_NAME_MAX 255
 #endif
 
@@ -93,6 +98,9 @@ int debug_level=1;
 static struct winsize termsize;
 
 
+/**
+   Number of nested calls to the block function. Unblock when this reaches 0.
+*/
 static int block_count=0;
 
 void common_destroy()
@@ -583,6 +591,9 @@ wcslcpy(wchar_t *dst, const wchar_t *src, size_t siz)
 	/* count does not include NUL */
 }
 
+/**
+   Fallback implementation if missing from libc
+*/
 wchar_t *wcsdup( const wchar_t *in )
 {
 	size_t len=wcslen(in);
@@ -598,6 +609,9 @@ wchar_t *wcsdup( const wchar_t *in )
 	
 }
 
+/**
+   Fallback implementation if missing from libc
+*/
 int wcscasecmp( const wchar_t *a, const wchar_t *b )
 {
 	if( *a == 0 )
@@ -615,6 +629,9 @@ int wcscasecmp( const wchar_t *a, const wchar_t *b )
 		return wcscasecmp( a+1,b+1);
 }
 
+/**
+   Fallback implementation if missing from libc
+*/
 int wcsncasecmp( const wchar_t *a, const wchar_t *b, int count )
 {
 	if( count == 0 )
@@ -1254,8 +1271,8 @@ static int sprint_rand_digits( char *str, int maxlen )
 
 /**
    Generate a filename unique in an NFS namespace by creating a copy of str and
-   appending .<hostname>.<pid> to it.  If gethostname() fails then a pseudo-
+   appending .{hostname}.{pid} to it.  If gethostname() fails then a pseudo-
-   random string is substituted for <hostname> - the randomness of the string
+   random string is substituted for {hostname} - the randomness of the string
    should be strong enough across different machines.  The main assumption 
    though is that gethostname will not fail and this is just a "safe enough"
    fallback.
@@ -1303,15 +1320,6 @@ static char *gen_unique_nfs_filename( const char *filename )
 	return newname;
 }
 
-/**
-   Attempt to acquire a lock based on a lockfile, waiting LOCKPOLLINTERVAL 
-   milliseconds between polls and timing out after timeout seconds, 
-   thereafter forcibly attempting to obtain the lock if force is non-zero.
-   Returns 1 on success, 0 on failure.
-   To release the lock the lockfile must be unlinked.
-   A unique temporary file named by appending characters to the lockfile name 
-   is used; any pre-existing file of the same name is subject to deletion.
-*/
 int acquire_lock_file( const char *lockfile, const int timeout, int force )
 {
 	int fd, timed_out = 0;

common.h

@@ -3,6 +3,9 @@
 */
 
 #ifndef FISH_COMMON_H
+/**
+   Header guard
+*/
 #define FISH_COMMON_H
 
 #include <wchar.h>
@@ -223,6 +226,9 @@ int read_blocked(int fd, void *buf, size_t count);
 */
 int writeb( tputs_arg_t b );
 
+/**
+   Exit program at once, leaving an error message about running out of memory
+*/
 void die_mem();
 
 /**
@@ -236,7 +242,7 @@ void common_destroy();
    program_name, followed by a colon and a whitespace.
    
    \param level the priority of the message. Lower number means higher priority. Messages with a priority_number higher than \c debug_level will be ignored..
-   \param the message format string. 
+   \param msg the message format string. 
 
    Example:
 
@@ -258,11 +264,39 @@ void debug( int level, wchar_t *msg, ... );
 wchar_t *escape( const wchar_t *in, 
 				 int escape_all );
 
-wchar_t *unescape( const wchar_t * in, int escape_special );
+/**
+   Expand backslashed escapes and substitute them with their unescaped
+   counterparts. Also optionally change the wildcards, the tilde
+   character and a few more into constants which are defined in a
+   private use area of Unicode. This assumes wchar_t is a unicode
+   character.  character set.
 
+   The result must be free()d. The original string is not modified. If
+   an invalid sequence is specified, 0 is returned.
+
+*/
+wchar_t *unescape( const wchar_t * in, 
+				   int escape_special );
+
+/**
+   Block SIGCHLD. Calls to block/unblock may be nested, and only once the nest count reaches zero wiull the block be removed.
+*/
 void block();
+
+/**
+   undo call to block().
+*/
 void unblock();
 
+/**
+   Attempt to acquire a lock based on a lockfile, waiting LOCKPOLLINTERVAL 
+   milliseconds between polls and timing out after timeout seconds, 
+   thereafter forcibly attempting to obtain the lock if force is non-zero.
+   Returns 1 on success, 0 on failure.
+   To release the lock the lockfile must be unlinked.
+   A unique temporary file named by appending characters to the lockfile name 
+   is used; any pre-existing file of the same name is subject to deletion.
+*/
 int acquire_lock_file( const char *lockfile, const int timeout, int force );
 
 /** 
@@ -282,7 +316,7 @@ int common_get_width();
 */
 int common_get_height();
 
-/*
+/**
   Handle a window change event by looking up the new window size and
   saving it in an internal variable used by common_get_wisth and
   common_get_height().

complete.c

@@ -309,7 +309,9 @@ static void clear_hash_entry( const void *key, const void *data )
 	free( (void *)data );
 }
 
-
+/**
+   Free hash value, but not hash key
+*/
 static void clear_hash_value( const void *key, const void *data )
 {
 	free( (void *)data );
@@ -2094,6 +2096,11 @@ void complete( const wchar_t *cmd,
 
 }
 
+/**
+   Print the GNU longopt style switch \c opt, and the argument \c
+   argument to the specified stringbuffer, but only if arguemnt is
+   non-null and longer than 0 characters.
+*/
 static void append_switch( string_buffer_t *out,
 						   const wchar_t *opt, 
 						   const wchar_t *argument )

complete.h

@@ -5,6 +5,9 @@
 */
 
 #ifndef FISH_COMPLETE_H
+/**
+   Header guard
+*/
 #define FISH_COMPLETE_H
 
 #include <wchar.h>

configure.ac

@@ -1,5 +1,5 @@
 # Process this file with autoconf to produce a configure script.
-AC_INIT(fish,1.16.0,axel@liljencrantz.se)
+AC_INIT(fish,1.16.1,axel@liljencrantz.se)
 
 AC_CANONICAL_TARGET
 

env.c

@@ -47,6 +47,9 @@
 */
 #define FISHD_CMD L"if which fishd >/dev/null; fishd ^/tmp/fish.%s.log; end"
 
+/**
+   Value denoting a null string
+*/
 #define ENV_NULL L"\x1d"
 
 /**
@@ -770,6 +773,9 @@ int env_exist( const wchar_t *key )
 	return item != 0;
 }
 
+/**
+   Returns true if the specified scope or any non-shadowed non-global subscopes contain an exported variable.
+*/
 static int local_scope_exports( env_node_t *n )
 {
 	
@@ -841,6 +847,9 @@ static void add_key_to_hash( const void *key,
 		hash_put( (hash_table_t *)aux, key, 0 );
 }
 
+/**
+   Add key to hashtable
+*/
 static void add_to_hash( const void *k, void *aux )
 {
 	hash_put( (hash_table_t *)aux,
@@ -848,6 +857,9 @@ static void add_to_hash( const void *k, void *aux )
 			  0 );
 }
 
+/**
+   Add key to list
+*/
 static void add_key_to_list( const void * key, 
 							 const void * val, 
 							 void *aux )

env_universal.h

@@ -1,4 +1,4 @@
-/** \file env_universl.h
+/** \file env_universal.h
 	Universal variable client library
 */
 
@@ -18,7 +18,7 @@ extern connection_t env_universal_server;
    Initialize the envuni library
 */
 void env_universal_init();
-/*
+/**
   Free memory used by envuni
 */
 void env_universal_destroy();

env_universal_common.c

@@ -65,12 +65,12 @@
    should be exported. Obviously, it needs to be allocated large
    enough to fit the value string.
 */
-typedef struct var_entry
+typedef struct var_uni_entry
 {
 	int export; /**< Whether the variable should be exported */
 	wchar_t val[0]; /**< The value of the variable */
 }
-var_entry_t;
+var_uni_entry_t;
 
 
 static void parse_message( wchar_t *msg,
@@ -81,6 +81,9 @@ static void parse_message( wchar_t *msg,
 */
 hash_table_t env_universal_var;
 
+/**
+   Callback function, should be called on all events
+*/
 void (*callback)( int type, 
 				  const wchar_t *key, 
 				  const wchar_t *val );
@@ -105,6 +108,9 @@ void env_universal_common_init( void (*cb)(int type, const wchar_t *key, const w
 	hash_init( &env_universal_var, &hash_wcs_func, &hash_wcs_cmp );
 }
 
+/**
+   Free both key and data
+*/
 static void erase( const void *key,
 				   const void *data )
 {
@@ -186,6 +192,9 @@ void read_message( connection_t *src )
 	}
 }
 
+/**
+   Remove variable with specified name
+*/
 static void remove_entry( wchar_t *name )
 {
 	void *k, *v;
@@ -197,6 +206,9 @@ static void remove_entry( wchar_t *name )
 	free( v );
 }
 
+/**
+   Test if the message msg contains the command cmd
+*/
 static int match( const wchar_t *msg, const wchar_t *cmd )
 {
 	size_t len = wcslen( cmd );
@@ -209,7 +221,9 @@ static int match( const wchar_t *msg, const wchar_t *cmd )
 	return 1;
 }
 
-
+/**
+   Parse message msg
+*/
 static void parse_message( wchar_t *msg, 
 						   connection_t *src )
 {
@@ -239,8 +253,8 @@ static void parse_message( wchar_t *msg,
 
 			val = unescape( val, 0 );
 			
-			var_entry_t *entry = 
+			var_uni_entry_t *entry = 
-				malloc( sizeof(var_entry_t) + sizeof(wchar_t)*(wcslen(val)+1) );			
+				malloc( sizeof(var_uni_entry_t) + sizeof(wchar_t)*(wcslen(val)+1) );			
 			if( !entry )
 				die_mem();
 			entry->export=export;
@@ -307,8 +321,13 @@ static void parse_message( wchar_t *msg,
 	}		
 }
 
-int try_send( message_t *msg,
+/**
-			  int fd )
+   Attempt to send the specified message to the specified file descriptor
+
+   \return 1 on sucess, 0 if the message could not be sent without blocking and -1 on error
+*/
+static int try_send( message_t *msg,
+					 int fd )
 {
 
 	debug( 3,
@@ -478,7 +497,7 @@ static void add_key_to_hash( const void *key,
 							 const void *data,
 							 void *aux )
 {
-	var_entry_t *e = (var_entry_t *)data;
+	var_uni_entry_t *e = (var_uni_entry_t *)data;
 	if( ( e->export && get_names_show_exported) || 
 		( !e->export && get_names_show_unexported) )
 		al_push( (array_list_t *)aux, key );
@@ -498,7 +517,7 @@ void env_universal_common_get_names( array_list_t *l,
 
 wchar_t *env_universal_common_get( const wchar_t *name )
 {
-	var_entry_t *e = (var_entry_t *)hash_get( &env_universal_var, name );	
+	var_uni_entry_t *e = (var_uni_entry_t *)hash_get( &env_universal_var, name );	
 	if( e )
 		return e->val;
 	return 0;	
@@ -506,18 +525,28 @@ wchar_t *env_universal_common_get( const wchar_t *name )
 
 int env_universal_common_get_export( const wchar_t *name )
 {
-	var_entry_t *e = (var_entry_t *)hash_get( &env_universal_var, name );
+	var_uni_entry_t *e = (var_uni_entry_t *)hash_get( &env_universal_var, name );
 	if( e )
 		return e->export;
 	return 0;
 }
 
+/**
+   Adds a variable creation message about the specified variable to
+   the specified queue. The function signature is non-obvious since
+   this function is used together with hash_foreach2, which requires
+   the specified function signature.
+
+   \param k the variable name
+   \param v the variable value
+   \param q the queue to add the message to
+*/
 static void enqueue( const void *k,
 					 const void *v,
 					 void *q)
 {
 	const wchar_t *key = (const wchar_t *)k;
-	const var_entry_t *val = (const var_entry_t *)v;
+	const var_uni_entry_t *val = (const var_uni_entry_t *)v;
 	dyn_queue_t *queue = (dyn_queue_t *)q;
 	
 	message_t *msg = create_message( val->export?SET_EXPORT:SET, key, val->val );

env_universal_common.h

@@ -88,7 +88,13 @@ typedef struct connection
 */
 typedef struct 
 {
+	/**
+	   Number of queues that contain this message. Once this reaches zero, the message should be deleted
+	*/
 	int count;
+	/**
+	   Message body. The message must be allocated using enough memory to actually contain the message.
+	*/
 	char body[0];
 }
 	message_t;
@@ -136,6 +142,9 @@ wchar_t *env_universal_common_get( const wchar_t *name );
 */
 int env_universal_common_get_export( const wchar_t *name );
 
+/**
+   Add messages about all existing variables to the specified connection
+*/
 void enqueue_all( connection_t *c );
 
 

event.c

@@ -1,6 +1,6 @@
-/** \file function.c
+/** \file event.c
 
-	Functions for storing and retrieving function information.
+	Functions for handling event triggers
 
 */
 #include <stdlib.h>
@@ -31,13 +31,22 @@
 */
 typedef struct
 {
+	/**
+	   Number of delivered signals
+	*/
 	int count;
+	/**
+	   Whether signals have been skipped
+	*/
 	int overflow;	
+	/**
+	   Array of signal events
+	*/
 	int signal[SIG_UNHANDLED_MAX];	
 }
 	signal_list_t;
 
-/*
+/**
   The signal event list. Actually two separate lists. One which is
   active, which is the one that new events is written to. The inactive
   one contains the events that are currently beeing performed.

event.h

@@ -1,6 +1,6 @@
 /** \file event.h
 
-Event handling library
+	Functions for handling event triggers
 
 */
 #ifndef FISH_EVENT_H

exec.c

@@ -40,7 +40,7 @@
 /**
    Prototype for the getpgid library function. The prototype for this
    function seems to be missing in glibc, at least I've not found any
-   combination of #includes, macros and compiler switches that will
+   combination of includes, macros and compiler switches that will
    include it.
 */
 pid_t getpgid( pid_t pid );

exec.h

@@ -3,6 +3,9 @@
 */
 
 #ifndef FISH_EXEC_H
+/**
+   Header guard
+*/
 #define FISH_EXEC_H
 
 #include <wchar.h>
@@ -20,7 +23,7 @@
 */
 void exec_init();
 
-/*
+/**
   Destroy dynamically allocated data and other resources used by the
   exec library
 */

expand.h

@@ -10,6 +10,9 @@
 */
 
 #ifndef FISH_EXPAND_H
+/**
+   Header guard
+*/
 #define FISH_EXPAND_H
 
 #include <wchar.h>
@@ -51,7 +54,7 @@
 
 #define DIRECTORIES_ONLY 32
 
-/*
+/**
   Use unencoded private-use keycodes for internal characters
 */
 #define EXPAND_RESERVED 0xf000
@@ -122,11 +125,9 @@ wchar_t *expand_one( wchar_t *in, int flag );
 /**
    Expand backslashed escapes and substitute them with their unescaped
    counterparts. Also optionally change the wildcards, the tilde
-   character and a few more into constants which are defined to be
+   character and a few more into constants which are defined in a
-   outside of the valid character space, but still inside the valid
+   private use area of Unicode. This assumes wchar_t is a unicode
-   space for a wchar_t. This assumes that a wchar_t is at least 32
+   character.  character set.
-   bits long AND that the characterset is UCS4 or some other 31-bit
-   character set.
 
    The result must be free()d. The original string is not modified. If
    an invalid sequence is specified, 0 is returned.

fish_tests.c

@@ -1,4 +1,4 @@
-/** \file main.c
+/** \file fish_tests.c
 	Various bug and feature tests. Compiled and run by make test.
 */
 
@@ -39,10 +39,19 @@
 #include "parser.h"
 #include "tokenizer.h"
 
+/**
+   Number of laps to run performance testing loop
+*/
 #define LAPS 50
 
+/**
+   Number of encountered errors
+*/
 static int err_count=0;
 
+/**
+   Print formatted output
+*/
 static void say( wchar_t *blah, ... )
 {
 	va_list va;
@@ -52,6 +61,9 @@ static void say( wchar_t *blah, ... )
 	wprintf( L"\n" );
 }
 
+/**
+   Print formatted error string
+*/
 static void err( wchar_t *blah, ... )
 {
 	va_list va;
@@ -64,16 +76,25 @@ static void err( wchar_t *blah, ... )
 	wprintf( L"\n" );
 }
 
+/**
+   Print ok message
+*/
 static void ok()
 {
 	wprintf( L"OK\n" );
 }
 
+/**
+   Compare two pointers
+*/
 static int pq_compare( void *e1, void *e2 )
 {
 	return e1-e2;
 }
 
+/**
+   Test priority queue functionality
+*/
 static int pq_test( int elements )
 {
 	int i;
@@ -114,7 +135,9 @@ static int pq_test( int elements )
 	}
 }
 
-
+/**
+   Test stack functionality
+*/
 static int stack_test( int elements )
 {
 	int i;
@@ -160,7 +183,9 @@ static int stack_test( int elements )
 	return res;
 }
 
-
+/**
+   Hash function for pointers
+*/
 static int hash_func( const void *data )
 {
 /*	srand( (int)data );
@@ -170,12 +195,18 @@ static int hash_func( const void *data )
 	return 127*((foo^0xefc7e214)) ^(foo<<11);	
 }
 
+/**
+   Pointer hash comparison function
+*/
 static int compare_func( const void *key1, const void *key2 )
 {
 	return key1==key2;
 }
 
 
+/**
+   Hashtable test
+*/
 static int hash_test( int elements )
 {
 	int i;
@@ -249,6 +280,9 @@ static int hash_test( int elements )
 	
 }
 
+/**
+   Arraylist test
+*/
 static int al_test( int sz)
 {
 	int i;	
@@ -280,6 +314,9 @@ static int al_test( int sz)
 	}
 }
 
+/**
+   Stringbuffer test
+*/
 static void sb_test()
 {
 	string_buffer_t b;
@@ -299,7 +336,9 @@ static void sb_test()
 	say( (wchar_t *)b.buff );
 }
 
-
+/**
+   Performs all tests of the util library
+*/
 static void test_util()
 {
 	int i;
@@ -346,8 +385,9 @@ static void test_util()
 }
 
 
-
+/**
-
+   Test the tokenizer
+*/
 static void test_tok()
 {
 	tokenizer t;
@@ -412,6 +452,9 @@ static void test_tok()
 		
 }
 
+/**
+   Test the parser
+*/
 static void test_parser()
 {
 	say( L"Testing parser" );
@@ -514,7 +557,9 @@ static int expand_test( const wchar_t *in, int flags, ... )
 		
 }
 
-
+/**
+   Test globbing and other parameter expantion
+*/
 static void test_expand()
 {
 	say( L"Testing parameter expantion" );
@@ -536,7 +581,9 @@ static void test_expand()
 	
 }
 
-
+/**
+   Test speed of completion calculations
+*/
 void perf_complete()
 {
 	wchar_t c;
@@ -607,7 +654,9 @@ void perf_complete()
 	
 }
 
-
+/**
+   Main test 
+*/
 int main( int argc, char **argv )
 {
 

fishd.c

@@ -350,12 +350,17 @@ void load_or_save( int save)
 	close( c.fd );
 }
 
+/**
+   Load variables from disk
+*/
 static void load()
 {
 	load_or_save(0);
 }
 
-
+/**
+   Save variables to disk
+*/
 static void save()
 {
 	load_or_save(1);
@@ -376,7 +381,9 @@ static void init()
 	load();	
 }
 
-
+/**
+   Main function for fishd
+*/
 int main( int argc, char ** argv )
 {
 	int child_socket, t;

input.c

@@ -263,6 +263,9 @@ void input_set_application( wchar_t *name )
 	current_application_mappings = (array_list_t *)hash_get( &all_mappings, name );	
 }
 
+/**
+   Get the mapping with the specified name
+*/
 static array_list_t *get_mapping( const wchar_t *mode )
 {
 
@@ -1109,6 +1112,9 @@ static void add_terminfo_mapping( const wchar_t *mode,
 	
 }
 
+/**
+   Call input_expand_sequence on seq, and add the result as a mapping
+*/
 static void add_escaped_mapping( const wchar_t *mode, 
 								 const wchar_t *seq,
 								 const wchar_t *desc, 
@@ -1122,7 +1128,9 @@ static void add_escaped_mapping( const wchar_t *mode,
 	}
 }
 
-
+/**
+   Add bindings common to emacs and vi
+*/
 static void add_common_bindings()
 {
 	static const wchar_t *name[] =
@@ -1204,6 +1212,9 @@ static void add_common_bindings()
 	}		
 }
 
+/**
+   Add emacs-specific bindings
+*/
 static void add_emacs_bindings()
 {	
 	add_escaped_mapping( L"emacs", (L"\\C-a"), L"Control-a", L"beginning-of-line" );
@@ -1216,6 +1227,9 @@ static void add_emacs_bindings()
 	add_terminfo_mapping( L"emacs", (key_npage), L"Page Down", L"end-of-history" );
 }
 
+/**
+   Add vi-specific bindings
+*/
 static void add_vi_bindings()
 {
 	add_mapping( L"vi", L"\e", L"Escape", L"bind -M vi-command" );
@@ -1246,6 +1260,10 @@ static void add_vi_bindings()
 	
 }
 
+/**
+   Handle interruptions to key reading by reaping finshed jobs and
+   propagating the interrupt to the reader.
+*/
 static int interrupt_handler()
 {
 	if( job_reap( 1 ) )
@@ -1313,6 +1331,9 @@ int input_init()
 	
 }
 
+/**
+   Free memory used by the specified mapping
+*/
 static void destroy_mapping( const void *key, const void *val )
 {
 	int i;
@@ -1344,7 +1365,9 @@ void input_destroy()
 	del_curterm( cur_term );
 }
 
-
+/**
+   Perform the action of the specified binding
+*/
 static wint_t input_exec_binding( mapping *m, const wchar_t *seq )
 {
 //	fwprintf( stderr, L"Binding %ls\n", m->command );
@@ -1398,7 +1421,6 @@ static wint_t input_exec_binding( mapping *m, const wchar_t *seq )
 /**
    Try reading the specified function mapping
 */
-
 static wint_t input_try_mapping( mapping *m)
 {
 	int j, k;

input_common.c

@@ -1,4 +1,4 @@
-/** \file input_common.h
+/** \file input_common.c
 	
 Implementation file for the low level input library
 

intern.c

@@ -17,6 +17,9 @@
 hash_table_t *intern_table=0;
 hash_table_t *intern_static_table=0;
 
+/**
+   Load static strings that are universally common. Currently only loads the empty string.
+*/
 static void intern_load_common_static()
 {
 	intern_static( L"" );
@@ -94,6 +97,9 @@ const wchar_t *intern_static( const wchar_t *in )
 	return res;
 }
 
+/**
+   Free the specified key/value pair. Should only be called by intern_free_all at shutdown
+*/
 static void clear_value( const void *key, const void *data )
 {
 	debug( 3,  L"interned string: '%ls'", data );	

intern.h

@@ -12,7 +12,7 @@
 /**
    Return an identical copy of the specified string from a pool of unique strings. If the string was not in the pool, add a copy.
 
-   \param The string to return an interned copy of
+   \param in the string to return an interned copy of
 */
 const wchar_t *intern( const wchar_t *in );
 
@@ -20,11 +20,13 @@ const wchar_t *intern( const wchar_t *in );
    Insert the specified string literal into the pool of unique
    strings. The string will not first be copied, and it will not be
    free'd on exit.
+
+   \param in the string to add to the interned pool
 */
 const wchar_t *intern_static( const wchar_t *in );
 
 /**
-   Free all interned strings
+   Free all interned strings. Only call this at shutdown.
 */
 void intern_free_all();
 

io.h

@@ -17,7 +17,9 @@ typedef struct io_data
 	int io_mode;
 	/** FD to redirect */
 	int fd;
-	/** parameter for redirection */
+	/** 
+		Type-specific parameter for redirection 
+	*/
 	union
 	{
 		/** Fds for IO_PIPE and for IO_BUFFER */
@@ -28,6 +30,9 @@ typedef struct io_data
 		int old_fd;
 	} param1
 	;
+	/** 
+		Second type-specific paramter for redirection
+	*/
 	union
 	{
 		/** file creation flags to send to open for IO_FILE */

parser.c

@@ -51,6 +51,10 @@ The fish parser. Contains functions for parsing code.
 */
 #define MAX_RECURSION_DEPTH 128
 
+/**
+   Message about reporting bugs, used on weird internal error to
+   hopefully get them to report stuff.
+*/
 #define BUGREPORT_MSG L"If this error can be reproduced, please send a bug report to %s."
 
 /**
@@ -147,7 +151,25 @@ static int parse_job( process_t *p,
 */
 typedef struct
 {
-	int exec, parse, level, skipped;
+	/**
+	   Time spent executing the specified command, including parse time for nested blocks
+	*/
+	int exec;
+	/**
+	   Time spent parsing the specified command, incvluding execution time for command substitutions
+	*/
+	int parse;
+	/**
+	   The block level of the specified command
+	*/
+	int level;
+	/**
+	   If the execution of this command was skipped
+	*/
+	int skipped;
+	/**
+	   The command string
+	*/
 	wchar_t *cmd;
 } profile_element_t;
 

wgetopt.c

@@ -1,3 +1,22 @@
+/** \file wgetopt.c
+	A version of the getopt library for use with wide character strings. 
+
+	This is simply the gnu getopt library, but converted for use with
+	wchar_t instead of char. This is not usually useful since the argv
+	array is always defined to be of type char**, but in fish, all
+	internal commands use wide characters and hence this library is
+	useful.
+
+	If you want to use this version of getopt in your program, simply
+	copy wgetopt.c and wgetopt.h into your program, include wgetopt.h,
+	and use all the regular getopt functions, prefixing every
+	function, global variable and structure with a 'w', and use only
+	wide character strings. There are no other functional changes in
+	this version of getopt besides using wide character strings.
+
+*/
+
+
 /* Getopt for GNU.
    NOTE: getopt is now part of the C library, so if you don't know what
    "Keep this file name-space clean" means, talk to roland@gnu.ai.mit.edu

wgetopt.h

@@ -1,7 +1,19 @@
 /** \file wgetopt.h
-	The getopt librar for wide character strings. 
+	A version of the getopt library for use with wide character strings. 
+
+	This is simply the gnu getopt library, but converted for use with
+	wchar_t instead of char. This is not usually useful since the argv
+	array is always defined to be of type char**, but in fish, all
+	internal commands use wide characters and hence this library is
+	useful.
+
+	If you want to use this version of getopt in your program, simply
+	copy wgetopt.c and wgetopt.h into your program, include wgetopt.h,
+	and use all the regular getopt functions, prefixing every
+	function, global variable and structure with a 'w', and use only
+	wide character strings. There are no other functional changes in
+	this version of getopt besides using wide character strings.
 
-	This is simply the gnu getopt library, but converted for use with wchar_t instead of char. This is not usually useful since the argv array is always defined to be of type char**, but in fish, all internal commands use wide characters and hence this library is usefull.
 */
 
 
@@ -89,54 +101,99 @@ extern int woptopt;
 
 struct woption
 {
+	/**
+	   long name for switch
+	*/
 #if defined (__STDC__) && __STDC__
   const wchar_t *name;
 #else
   wchar_t *name;
 #endif
-  /* has_arg can't be an enum because some compilers complain about
+	/** 
-     type mismatches in all the code that assumes it is an int.  */
+		Must be one of no_argument, required_argument and
+		optional_argument.
+
+		has_arg can't be an enum because some compilers complain about
+		type mismatches in all the code that assumes it is an int.  
+	*/
   int has_arg;
+
+	/**
+	  If non-null, the flag whose value should be set if this switch is encountered
+	*/
   int *flag;
+
+	/**
+	  If \c flag is non-null, this is the value that flag will be set
+	  to. Otherwise, this is the return-value of the function call.
+	*/
   int val;
 };
 
 /* Names for the values of the `has_arg' field of `struct option'.  */
 
+/**
+   Specifies that a switch does not accept an argument
+*/
 #define	no_argument		0
+/**
+   Specifies that a switch requires an argument
+*/
 #define required_argument	1
+/**
+   Specifies that a switch accepts an optional argument
+*/
 #define optional_argument	2
 
 #if defined (__STDC__) && __STDC__
 #ifdef __GNU_LIBRARY__
-/* Get options from argument list */
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt (int argc, wchar_t *const *argv, const wchar_t *shortopts);
 #else /* not __GNU_LIBRARY__ */
-/* Get options from argument list */
+
 extern int wgetopt ();
 #endif /* __GNU_LIBRARY__ */
-/* Get options from argument list */
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt_long (int argc, wchar_t *const *argv, const wchar_t *shortopts,
 		        const struct woption *longopts, int *longind);
-/* Get options from argument list */
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt_long_only (int argc, wchar_t *const *argv,
 			     const wchar_t *shortopts,
 		             const struct woption *longopts, int *longind);
 
-/** Internal only.  Users should not call this directly.  */
+/** 
+	Internal only.  Users should not call this directly.  
+*/
 extern int _wgetopt_internal (int argc, wchar_t *const *argv,
 			     const wchar_t *shortopts,
 		             const struct woption *longopts, int *longind,
 			     int long_only);
 #else /* not __STDC__ */
-/* Get options from argument list */
+
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt ();
-/* Get options from argument list */
+
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt_long ();
-/* Get options from argument list */
+
+/** 
+	Get options from argument list. See the glibc manual for information on how to use this function.
+ */
 extern int wgetopt_long_only ();
 
-/* Get options from argument list */
+/** 
+	Internal only.  Users should not call this directly.  
+*/
 extern int _wgetopt_internal ();
 #endif /* __STDC__ */
 

wildcard.h

@@ -8,6 +8,9 @@
 */
 
 #ifndef FISH_WILDCARD_H
+/**
+   Header guard
+*/
 #define FISH_WILDCARD_H
 
 #include <wchar.h>
@@ -20,6 +23,9 @@
 
 #define WILDCARD_RESERVED 0xf400
 
+/**
+   Enumeration of all wildcard types
+*/
 enum
 {
 	/** Character representing any character except '/' */