Add lots of new code comments.

darcs-hash:20080113164747-75c98-9d0cefd27be7aef7ba60772616d9da7e6bb52912.gz

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

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
 */

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;
 
 /**

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;

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

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
 */

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 )

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;

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

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

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

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