Documentation updates. Fixes a few formating bugs, adds various minor missing api documentation, fixes a few typos. Also fixes a few tiny code issues, mostly missing consts, etc

darcs-hash:20060617130708-ac50b-cc2ec5aa3e4bfb8e28d7b86441bfb4661f1dd7e7.gz

19 files changed, 222 insertions, 34 deletions

diff --git a/builtin.c b/builtin.c
index bd2bc501..6f3e2afb 100644
--- a/builtin.c
+++ b/builtin.c
@@ -15,7 +15,7 @@
 
 	4). Add an entry to the BUILTIN_DOC_SRC variable of Makefile.in. Note that the entries should be sorted alphabetically!
 
-	5). Add an entry to the manual at the builtin-overview subsection. Note that the entries should be sorted alphabetically!
+	5). Add an entry to the manual at the builtin-overview subsection of doc_src/doc.hdr. Note that the entries should be sorted alphabetically!
 
 	6). Use 'darcs add doc_src/NAME.txt' to start tracking changes to the documentation file.
 
@@ -89,10 +89,22 @@
 */
 #define FG_MSG _( L"Send job %d, '%ls' to foreground\n" )
 
+/**
+   Datastructure to describe a builtin. 
+*/
 typedef struct builtin_data
 {
+	/**
+	   Name of the builtin
+	*/
 	const wchar_t *name;
+	/**
+	   Function pointer tothe builtin implementation
+	*/
 	int (*func)(wchar_t **argv);
+	/**
+	   Description of what the builtin does
+	*/
 	const wchar_t *desc;
 }
 	builtin_data_t;
@@ -153,6 +165,9 @@ void builtin_wperror( const wchar_t *s)
 	}
 }
 
+/**
+   Count the number of times the specified character occurs in the specified string
+*/
 static int count_char( const wchar_t *str, wchar_t c )
 {
 	int res = 0;
@@ -1979,6 +1994,7 @@ static int builtin_cd( wchar_t **argv )
 	wchar_t *dir;
 	int res=0;
 	void *context = halloc( 0, 0 );
+
 	
 	if( argv[1]  == 0 )
 	{
@@ -2776,6 +2792,9 @@ static int builtin_case( wchar_t **argv )
   Below are functions for handling the builtin commands
 */
 
+/**
+   Data about all the builtin commands in fish
+*/
 const static builtin_data_t builtin_data[]=
 {
 	{
diff --git a/builtin.h b/builtin.h
index 511a046b..bd99808a 100644
--- a/builtin.h
+++ b/builtin.h
@@ -62,6 +62,9 @@ enum
 */
 #define BUILTIN_FOR_ERR_IN _( L"%ls: Second argument must be 'in'\n" )
 
+/**
+   Error message when too many arguments are supplied to a builtin
+*/
 #define BUILTIN_ERR_TOO_MANY_ARGUMENTS _( L"%ls: Too many arguments\n" )
 
 /**
@@ -150,6 +153,11 @@ int builtin_count_args( wchar_t **argv );
 void builtin_print_help( wchar_t *cmd, string_buffer_t *b );
 
 
+/**
+   Slightly kludgy function used with 'complete -C' in order to make
+   the commandline builtin operate on the string to complete instead
+   of operating on whatever is to be completed.
+*/
 const wchar_t *builtin_complete_get_temporary_buffer();
 
 /** 
@@ -166,6 +174,6 @@ void builtin_wperror( const wchar_t *s);
 
    \param cmd The command for which to obtain help text
 */
-char *builtin_help_get( wchar_t *cmd );
+char *builtin_help_get( const wchar_t *cmd );
 
 #endif
diff --git a/builtin_commandline.c b/builtin_commandline.c
index 951eb788..42eb9016 100644
--- a/builtin_commandline.c
+++ b/builtin_commandline.c
@@ -63,6 +63,9 @@ static const wchar_t *get_buffer()
 	return buff;
 }
 
+/**
+   Returns the position of the cursor
+*/
 static int get_cursor_pos()
 {
 	const wchar_t *buff = builtin_complete_get_temporary_buffer();
diff --git a/builtin_complete.c b/builtin_complete.c
index 7ae60237..6531fd2b 100644
--- a/builtin_complete.c
+++ b/builtin_complete.c
@@ -25,6 +25,9 @@ Functions used for implementing the complete builtin.
 #include "reader.h"
 #include "translate.h"
 
+/**
+   Internal storage for the builtin_get_temporary_buffer() function.
+*/
 const static wchar_t *temporary_buffer;
 
 /*
@@ -36,6 +39,9 @@ const static wchar_t *temporary_buffer;
   short switch and one long switch.
 */
 
+/**
+   Silly function
+*/
 static void	builtin_complete_add2( const wchar_t *cmd,
 								   int cmd_type,
 								   const wchar_t *short_opt,
@@ -107,6 +113,9 @@ static void	builtin_complete_add2( const wchar_t *cmd,
 	}	
 }
 
+/**
+   Silly function
+*/
 static void	builtin_complete_add( array_list_t *cmd, 
 								  array_list_t *path,
 								  const wchar_t *short_opt,
@@ -150,6 +159,9 @@ static void	builtin_complete_add( array_list_t *cmd,
 	
 }
 
+/**
+   Silly function
+*/
 static void builtin_complete_remove3( wchar_t *cmd,
 									  int cmd_type,
 									  wchar_t short_opt,
@@ -166,6 +178,9 @@ static void builtin_complete_remove3( wchar_t *cmd,
 	}	
 }
 
+/**
+   Silly function
+*/
 static void	builtin_complete_remove2( wchar_t *cmd,
 									  int cmd_type,
 									  const wchar_t *short_opt,
@@ -214,6 +229,9 @@ static void	builtin_complete_remove2( wchar_t *cmd,
 	
 }
 
+/**
+   Silly function
+*/
 static void	builtin_complete_remove( array_list_t *cmd, 
 									 array_list_t *path,
 									 const wchar_t *short_opt,
@@ -363,7 +381,7 @@ static int builtin_complete( wchar_t **argv )
 		
 		int opt = wgetopt_long( argc,
 								argv, 
-								L"a:c:p:s:l:o:d:frxeun:C:h", 
+								L"a:c:p:s:l:o:d:frxeun:C::h", 
 								long_options, 
 								&opt_index );
 		if( opt == -1 )
diff --git a/builtin_help.hdr b/builtin_help.hdr
index c2671a5f..092bb5ee 100644
--- a/builtin_help.hdr
+++ b/builtin_help.hdr
@@ -16,8 +16,6 @@
 #include "common.h"
 #include "halloc_util.h"
 
-static int is_help_init=0;
-
 /**
 	Hashtable storing the help text
 */
@@ -25,17 +23,22 @@ static hash_table_t tbl;
 
 static void builtin_help_init();
 
-char *builtin_help_get( wchar_t *cmd )
+char *builtin_help_get( const wchar_t *cmd )
 {
-	if( !is_help_init )
-	{
-		builtin_help_init();
-	}
+	builtin_help_init();
+
 	return (char *)hash_get( &tbl, (void *)cmd );
 }
 
+/**
+	Initialize help hash table. Don't invoke it manually, 
+	it is called by builtin_help_get automatically.
+*/
 static void builtin_help_init()
 {
-	is_help_init = 1;
+	static int is_help_init = 0;
+	if( is_help_init )
+		return;
+	is_help_init=1;
 	halloc_register_function( global_context, (void (*)(void *))&hash_destroy, &tbl );
 	hash_init( &tbl, &hash_wcs_func, &hash_wcs_cmp );
diff --git a/builtin_set.c b/builtin_set.c
index 6841aeb4..c41cd437 100644
--- a/builtin_set.c
+++ b/builtin_set.c
@@ -179,8 +179,9 @@ static int my_env_set( const wchar_t *key, array_list_t *val, int scope )
 	\param indexes the list to insert the new indexes into
 	\param src the source string to parse
 	\param name the name of the element. Return null if the name in \c src does not match this name
+	\param the number of elements in the array to parse. 
 
-	\return the number of indexes parsed, or -1 on error
+	\return the total number of indexes parsed, or -1 on error
 */
 static int parse_index( array_list_t *indexes,
 						const wchar_t *src,
diff --git a/common.h b/common.h
index ce5ff3a0..900cd567 100644
--- a/common.h
+++ b/common.h
@@ -103,16 +103,39 @@ void sort_list( array_list_t *comp );
 /**
    Returns a newly allocated wide character string equivalent of the
    specified multibyte character string
+
+   This function encodes illegal character sequences in a reversible
+   way using the private use area.
 */
 wchar_t *str2wcs( const char *in );
+
+/**
+   Converts the narrow character string \c in into it's wide
+   equivalent, stored in \c out. \c out must have enough space to fit
+   the entire string.
+
+   This function encodes illegal character sequences in a reversible
+   way using the private use area.
+*/
 wchar_t *str2wcs_internal( const char *in, wchar_t *out );
 
 /**
    Returns a newly allocated multibyte character string equivalent of
    the specified wide character string
+
+   This function decodes illegal character sequences in a reversible
+   way using the private use area.
 */
 char *wcs2str( const wchar_t *in );
 
+/**
+   Converts the wide character string \c in into it's narrow
+   equivalent, stored in \c out. \c out must have enough space to fit
+   the entire string.
+
+   This function decodes illegal character sequences in a reversible
+   way using the private use area.
+*/
 char *wcs2str_internal( const wchar_t *in, char *out );
 
 /**
diff --git a/complete.c b/complete.c
index c170ecff..4d00abbc 100644
--- a/complete.c
+++ b/complete.c
@@ -1228,6 +1228,9 @@ static void complete_cmd_desc( const wchar_t *cmd, array_list_t *comp )
 	free( lookup_cmd );
 }
 
+/**
+   Returns a description for the specified function
+*/
 static const wchar_t *complete_function_desc( const wchar_t *fn )
 {
 	const wchar_t *res = function_get_desc( fn );
@@ -1548,6 +1551,14 @@ static int short_ok( wchar_t *arg,
 	return 1;
 }
 
+/**
+   This is an event handler triggered when the definition of a
+   specifiec function is changed. It automatcally removes the
+   specified function.
+
+   This is to make sure that the function disappears if the file is
+   removed or if ti contains a syntax error.
+*/
 static void complete_load_handler( const wchar_t *cmd )
 {
 	complete_remove( cmd, COMMAND, 0, 0 );
diff --git a/complete.h b/complete.h
index b8ad910c..2a9690b0 100644
--- a/complete.h
+++ b/complete.h
@@ -1,10 +1,12 @@
 /** \file complete.h
 	Prototypes for functions related to tab-completion.
 
-	These functions are used for storing and retrieving tab-completion data, as well as for performing tab-completion.
+	These functions are used for storing and retrieving tab-completion
+	data, as well as for performing tab-completion.
 */
 
 #ifndef FISH_COMPLETE_H
+
 /**
    Header guard
 */
@@ -14,29 +16,53 @@
 
 #include "util.h"
 
-/** Use all completions */
+/** 
+	Use all completions 
+*/
 #define SHARED 0
-/** Do not use file completion */
+/** 
+	Do not use file completion 
+*/
 #define NO_FILES 1
-/** Require a parameter after completion */
+/** 
+	Require a parameter after completion 
+*/
 #define NO_COMMON 2
-/** Only use the argument list specifies with completion after option. This is the same as (NO_FILES & NO_COMMON) */
+/** 
+	Only use the argument list specifies with completion after
+	option. This is the same as (NO_FILES & NO_COMMON)
+*/
 #define EXCLUSIVE 3
 
-/** Command is a path */
+/** 
+	Command is a path 
+*/
 #define PATH 1
-/** Command is not a path */
+/** 
+	Command is not a path 
+*/
 #define COMMAND 0
 
-/** Separateor between completion and description*/
+/** 
+	Separator between completion and description
+*/
 #define COMPLETE_SEP L'\004'
-/** Separateor between completion and description*/
+
+/** 
+	Separator between completion and description
+*/
 #define COMPLETE_SEP_STR L"\004"
 
+/**
+   Separator between completion items in fish_pager. This is used for
+   completion grouping, e.g. when putting completions with the same
+   descriptions on the same line.
+*/
 #define COMPLETE_ITEM_SEP L'\uf500'
 
 /**
-   Character that separates the completion and description on programmable completions
+   Character that separates the completion and description on
+   programmable completions
 */
 #define PROG_COMPLETE_SEP L'\t'
 
diff --git a/doc_src/doc.hdr b/doc_src/doc.hdr
index e2da65fb..7646b2df 100644
--- a/doc_src/doc.hdr
+++ b/doc_src/doc.hdr
@@ -268,8 +268,8 @@ searches through any directories in the array variable
 loaded when needed. A function definition file must have a filename
 consisting of the name of the function plus the suffix '.fish'.  
 
-The default value for \$fish_function_path is ~/.fish.d/functions,
-/etc/fish.d/functions /usr/share/fish/functions. The exact path to the
+The default value for \$fish_function_path is \c ~/.fish.d/functions
+\c /etc/fish.d/functions \c /usr/share/fish/functions. The exact path to the
 last two of these may be slighly different depending on what install
 path prefix was chosen at configuration time. The rationale behind
 having three different directories is that the first one is for user
@@ -787,7 +787,7 @@ the string __FISH or __fish. These should be ignored by the user.
 The colors used by fish for syntax highlighting can be configured by
 changing the values of a various variables. The value of these
 variables can be one of the colors accepted by the <a
-href='commands.html#set_color'>\c set_color</a> command. The \c --bold
+href='commands.html#set_color'>set_color</a> command. The \c --bold
 or \c -b switches accepted by \c set_color are also accepted.
 
 The following variables are available to change the highligting colors
@@ -819,7 +819,7 @@ Example:
 
 To make errors highlighted and red, use:
 
-<code>set fish_color_error red --bold</code>D
+<code>set fish_color_error red --bold</code>
 
 \subsection variables-locale Locale variables
 
@@ -1236,7 +1236,7 @@ href='fish-users@lists.sf.net'>fish-users@lists.sf.net</a>.
 - Complete vi-mode key bindings
 - More completions (for example xterm, vim, 
 konsole, gnome-terminal, dcop, cron,
-rlogin, telnet, rsync, arch, finger, nice, locate, 
+rlogin, rsync, arch, finger, nice, locate, 
 bibtex, aspell, xpdf,
 compress, wine, xmms, dig, wine, batch, cron, 
 g++, javac, java, gcj, lpr, doxygen, whois, find)
@@ -1285,9 +1285,6 @@ Older versions of Doxygen has bugs in the man-page generation which
 cause the builtin help to render incorrectly. Version 1.2.14 is known
 to have this problem.
 
-
-
-
 */
 /** \page design Design document
 
diff --git a/fallback.h b/fallback.h
index 7a245f47..428f98c3 100644
--- a/fallback.h
+++ b/fallback.h
@@ -299,6 +299,9 @@ int del_curterm(TERMINAL *oterm);
 */
 struct drand48_data
 {
+	/**
+	   Seed value
+	*/
 	unsigned int seed;
 }
 	;
diff --git a/fish_pager.c b/fish_pager.c
index c3053297..e947a362 100644
--- a/fish_pager.c
+++ b/fish_pager.c
@@ -97,13 +97,34 @@ static wchar_t *hightlight_var[] =
 static string_buffer_t out_buff;
 static FILE *out_file;
 
+/**
+   Data structure describing one or a group of related completions
+ */
 typedef struct 
 {
+	/**
+	   The list of all completin strings this entry applies to
+	*/
 	array_list_t *comp;
+	/**
+	   The description
+	*/
 	wchar_t *desc;
+	/**
+	   On-screen width of the completion string
+	*/
 	int comp_width;	
+	/**
+	   On-screen width of the description information
+	*/
 	int desc_width;	
+	/**
+	   Preffered total width
+	*/
 	int pref_width;
+	/**
+	   Minimum acceptable width
+	*/
 	int min_width;
 }
 	comp_t;
diff --git a/function.c b/function.c
index 6450cb35..4c8f87e9 100644
--- a/function.c
+++ b/function.c
@@ -36,9 +36,22 @@ typedef struct
 	wchar_t *cmd;
 	/** Function description */
 	wchar_t *desc;	
+	/**
+	   File where this function was defined
+	*/
 	const wchar_t *definition_file;
+	/**
+	   Line where definition started
+	*/
 	int definition_offset;	
+	/**
+	   Flag for specifying functions which are actually key bindings
+	*/
 	int is_binding;
+	
+	/**
+	   Flag for specifying that this function was automatically loaded
+	*/
 	int is_autoload;
 }
 	function_data_t;
@@ -47,6 +60,12 @@ typedef struct
    Table containing all functions
 */
 static hash_table_t function;
+
+/**
+   Kludgy flag set by the load function in order to tell function_add
+   that the function being defined is autoloaded. There should be a
+   better way to do this...
+*/
 static int is_autoload = 0;
 
 /**
diff --git a/halloc_util.c b/halloc_util.c
index 766ce17d..a79c4f83 100644
--- a/halloc_util.c
+++ b/halloc_util.c
@@ -1,4 +1,4 @@
-/** \file halloc.c
+/** \file halloc_util.c
 
     A hierarchical memory allocation system. Works just like talloc
 	used in Samba, except that an arbitrary block allocated with
diff --git a/history.c b/history.c
index 39db5c24..dd7c5d7c 100644
--- a/history.c
+++ b/history.c
@@ -41,15 +41,20 @@ typedef struct
 	   Number of entries
 	*/
 	int count;
+
 	/**
 	   Last history item
 	*/
 	ll_node_t *last;
+
 	/**
 	   The last item loaded from file
 	*/
 	ll_node_t *last_loaded;
 
+	/**
+	   Set to one if the file containing the saved history has been loaded
+	*/
 	int is_loaded;
 }
 	history_data;
@@ -79,7 +84,9 @@ static int past_end =1;
 static int history_count=0;
 
 /**
-   The name of the current history list. The name is used to switch between history lists for different commands as sell as for deciding the name of the file to save the history in.
+   The name of the current history list. The name is used to switch
+   between history lists for different commands as sell as for
+   deciding the name of the file to save the history in.
 */
 static wchar_t *mode_name;
 
diff --git a/parser.c b/parser.c
index 7206704f..1131f2f0 100644
--- a/parser.c
+++ b/parser.c
@@ -256,15 +256,29 @@ The fish parser. Contains functions for parsing code.
 */
 #define ERR_STR_SZ 1024
 
+/**
+   Datastructure to describe a block type, like while blocks, command substitution blocks, etc.
+*/
 struct block_lookup_entry
 {
+	/**
+	   The block type id. The legal values are defined in parser.h.
+	*/
 	int type;
+	/**
+	   The name of the builtin that creates this type of block, if any. 
+	*/
 	const wchar_t *name;
+	/**
+	   A description of this block type
+	*/
 	const wchar_t *desc;
 }
 	;
 
-
+/**
+   List of all legal block types
+*/
 const static struct block_lookup_entry block_lookup[]=
 {
 	{
diff --git a/util.h b/util.h
index 300b15e1..e15c211b 100644
--- a/util.h
+++ b/util.h
@@ -1,5 +1,11 @@
 /** \file util.h
 	Generic utilities library.
+
+	All containers in this library except strinb_buffer_t are written
+	so that they don't allocate any memory until the first element is
+	inserted into them. That way it is known to be very cheap to
+	initialize various containers at startup, supporting the fish
+	notion of doing as much lazy initalization as possible.
 */
 
 #ifndef FISH_UTIL_H
diff --git a/wildcard.h b/wildcard.h
index 85677b25..9133b0fb 100644
--- a/wildcard.h
+++ b/wildcard.h
@@ -57,7 +57,7 @@ enum
 
 	\param wc The wildcard string
 	\param base_dir The base directory of the filesystem to perform the match against
-	\param status flags for the search. Can be any combination of ACCEPT_INCOMPLETE and EXECUTABLES_ONLY
+	\param flags flags for the search. Can be any combination of ACCEPT_INCOMPLETE and EXECUTABLES_ONLY
 	\param out The list in which to put the output
 
 	\return 1 if matches where found, 0 otherwise.
diff --git a/wutil.h b/wutil.h
index 31651f33..666ae67c 100644
--- a/wutil.h
+++ b/wutil.h
@@ -15,8 +15,14 @@
 #include <sys/types.h>
 #include <stdarg.h>
 
+/**
+   Wide version of the dirent data structure
+*/
 struct wdirent
 {
+	/**
+	   The name of the current directory
+	*/
 	wchar_t *d_name;
 }
 	;
@@ -97,6 +103,9 @@ int wchdir( const wchar_t * dir );
 */
 wchar_t *wrealpath(const wchar_t *pathname, wchar_t *resolved_path);
 
+/**
+   Wide character version of readdir()
+*/
 struct wdirent *wreaddir(DIR *dir );
 
 /**