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, 
-				 int cut_at_cursor, 
-				 int tokenize )
+/**
+   Output the specified selection.
+
+   \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-
-   random string is substituted for <hostname> - the randomness of the string
+   appending .{hostname}.{pid} to it.  If gethostname() fails then a pseudo-
+   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().