Fixes to api documentation, added .PHONY to makefile actions, made a few private functions static

darcs-hash:20060123204014-ac50b-b9d2a10c7f00945b5d9d244cb3b8c1489fe280de.gz

Makefile.in

@@ -183,15 +183,17 @@ TRANSLATIONS := $(TRANSLATIONS_SRC:.po=.gmo)
 all: $(PROGRAMS) user_doc
 	@echo fish has now been built. 
 	@echo Use \'make install\' to install fish.
+.PHONY: all
 
 debug:
 	make fish CFLAGS="-O0 -Wno-unused -Werror -g @INCLUDEDIR@ -Wall -std=gnu99 -fno-strict-aliasing"
+.PHONY: debug
 
 # User documentation, describing the features of the fish shell.
 user_doc: doc.h Doxyfile.user user_doc.head.html
 	doxygen Doxyfile.user
 
-#Source code documentation. Also includes user documentation.
+# Source code documentation. Also includes user documentation.
 doc: *.h *.c doc.h Doxyfile builtin_help.c
 	doxygen; 
 
@@ -205,6 +207,7 @@ doc/refman.pdf: doc
 
 test: $(PROGRAMS) fish_tests
 	./fish_tests; cd tests; ../fish <test.fish;
+.PHONY: test
 
 xsel-0.9.6:
 	tar -xf xsel-0.9.6.tar
@@ -325,6 +328,10 @@ builtin_help.c: $(BUILTIN_DOC_HDR) doc_src/count.doxygen gen_hdr2 gen_hdr.sh bui
 	echo "}" >>$@
 #man -- doc_src/builtin_doc/man/man1/`basename $@ .c`.1 | cat -s | ./gen_hdr2 >>$@
 
+#
+# The build rules for installing/uninstalling
+#
+
 install: all install-translations
 	$(INSTALL) -m 755 -d $(DESTDIR)$(bindir) 
 	for i in $(PROGRAMS); do\
@@ -358,6 +365,7 @@ install: all install-translations
 	@echo \* use the command \'chsh -s $(DESTDIR)$(bindir)/fish\'.
 	@echo
 	@echo Have fun!
+.PHONY: install
 
 uninstall: uninstall-translations
 	for i in $(PROGRAMS); do \
@@ -371,6 +379,7 @@ uninstall: uninstall-translations
 	for i in fish.1* @XSEL_MAN@ mimedb.1* fishd.1* set_color.1* count.1*; do \
 		rm $(DESTDIR)$(mandir)/man1/$$i; \
 	done;
+.PHONY: uninstall
 
 install-translations: $(TRANSLATIONS)
 	if test $(HAVE_GETTEXT) = 1; then \
@@ -380,6 +389,7 @@ install-translations: $(TRANSLATIONS)
 			echo $(DESTDIR)$(datadir)/locale/`basename $$i .gmo`/LC_MESSAGES/fish.mo;\
 		done; \
 	fi
+.PHONY: install-translations
 
 uninstall-translations: 
 	if test $(HAVE_GETTEXT) = 1; then \
@@ -387,8 +397,12 @@ uninstall-translations:
 			rm -f $(DESTDIR)$(datadir)/locale/`basename $$i .po`/LC_MESSAGES/fish.mo; \
 		done; \
 	fi
+.PHONY: uninstall-translations
+
+#
+# The build rules for all the commands
+#
 
-# The fish shell
 fish: $(FISH_OBJS) 
 	$(CC) $(FISH_OBJS) $(LDFLAGS) -o $@
 
@@ -412,11 +426,16 @@ set_color: set_color.o doc_src/set_color.c
 tokenizer_test: tokenizer.c tokenizer.h util.o wutil.o common.o
 	$(CC) ${CFLAGS} tokenizer.c util.o wutil.o common.o -D TOKENIZER_TEST $(LDFLAGS) -o $@
 
+# Neat little program to show output from terminal
 key_reader: key_reader.o input_common.o common.o env_universal.o env_universal_common.o util.o wutil.o
 	$(CC) key_reader.o input_common.o common.o env_universal.o env_universal_common.o util.o wutil.o $(LDFLAGS) -o $@
 
+#
+# Update dependencies
+#
 depend:
 	makedepend -fMakefile.in -Y *.c 
+.PHONY: depend
 
 # Copy all the source files into a new directory and use tar to create
 # an archive from it. Simplest way I could think of to make an archive
@@ -455,11 +474,17 @@ rpm: fish-@PACKAGE_VERSION@.tar.bz2
 	rpmbuild -ba --clean /usr/src/redhat/SPECS/fish.spec
 	mv /usr/src/redhat/RPMS/*/fish*@PACKAGE_VERSION@*.rpm .
 	mv /usr/src/redhat/SRPMS/fish*@PACKAGE_VERSION@*.src.rpm .
+.PHONY: rpm
+
+#
+# Cleanup targets
+#
 
 distclean: clean
 	rm -f fish.spec doc_src/fish.1 doc_src/Doxyfile 
 	rm -f init/fish init/fish_interactive.fish init/fish_complete.fish
 	rm -f config.status config.log config.h Makefile
+.PHONY: distclean
 
 clean:
 	rm -f *.o doc.h doc_src/*.doxygen doc_src/*.c builtin_help.c 
@@ -475,6 +500,7 @@ clean:
 	rm -rf fish-@PACKAGE_VERSION@
 	rm -rf xsel-0.9.6/
 	rm -f $(TRANSLATIONS)
+.PHONY: clean
 
 # DO NOT DELETE THIS LINE -- make depend depends on it.
 

builtin.c

@@ -646,6 +646,10 @@ static int builtin_exec( wchar_t **argv )
 	return 1;
 }
 
+/**
+   Print the definitions of the given function to sb_out
+   stringbuffer. Used by the functions builtin.
+*/
 static void functions_def( wchar_t *name )
 {
 	const wchar_t *desc = function_get_desc( name );
@@ -2260,6 +2264,9 @@ static int cpu_use( job_t *j )
 }
 #endif
 
+/**
+   Print information about the specified job
+*/
 static void builtin_jobs_print( job_t *j, int mode, int header )
 {
 	process_t *p;

builtin.h

@@ -47,8 +47,14 @@ enum
 */
 #define BUILTIN_ERR_UNKNOWN	_( L"%ls: Unknown option '%ls'\n" )
 
+/**
+   Error message for invalid character in variable name
+*/
 #define BUILTIN_ERR_VARCHAR _( L"%ls: Invalid character '%lc' in variable name. Only alphanumerical characters and underscores are valid in a variable name.\n" )
 
+/**
+   Error message for invalid (empty) variable name
+*/
 #define BUILTIN_ERR_VARNAME_ZERO _( L"%ls: Variable name can not be the empty string\n" )
 
 /**

builtin_complete.c

@@ -1,4 +1,4 @@
-/** \file builtin_commandline.c Functions defining the complete builtin
+/** \file builtin_complete.c Functions defining the complete builtin
 
 Functions used for implementing the complete builtin. 
 

common.c

@@ -88,8 +88,6 @@ int error_max=1;
 
 wchar_t ellipsis_char;
 
-static int c1=0, c2=0, c3=0, c4=0, c5;
-
 char *profile=0;
 
 wchar_t *program_name;
@@ -107,6 +105,9 @@ static struct winsize termsize;
 */
 static int block_count=0;
 
+/**
+   String buffer used by the wsetlocale function
+*/
 static string_buffer_t *setlocale_buff=0;
 
 
@@ -117,8 +118,6 @@ void common_destroy()
 		sb_destroy( setlocale_buff );
 		free( setlocale_buff );
 	}
-	
-	debug( 3, L"Calls: wcsdupcat %d, wcsdupcat2 %d, wcsndup %d, str2wcs %d, wcs2str %d", c1, c2, c3, c4, c5 );
 }
 
 
@@ -256,8 +255,6 @@ void sort_list( array_list_t *comp )
 
 wchar_t *str2wcs( const char *in )
 {
-	c4++;
-	
 	wchar_t *res;
 	
 	res = malloc( sizeof(wchar_t)*(strlen(in)+1) );
@@ -299,9 +296,8 @@ void error_reset()
 
 char *wcs2str( const wchar_t *in )
 {
-	c5++;
-
 	char *res = malloc( MAX_UTF8_BYTES*wcslen(in)+1 );
+
 	if( res == 0 )
 	{
 		die_mem();
@@ -311,7 +307,7 @@ char *wcs2str( const wchar_t *in )
 			  in,
 			  MAX_UTF8_BYTES*wcslen(in)+1 );
 
-//	res = realloc( res, strlen( res )+1 );
+	res = realloc( res, strlen( res )+1 );
 
 	return res;
 }
@@ -340,15 +336,11 @@ char **wcsv2strv( const wchar_t **in )
 
 wchar_t *wcsdupcat( const wchar_t *a, const wchar_t *b )
 {
-	c1++;
-
 	return wcsdupcat2( a, b, 0 );
 }
 
 wchar_t *wcsdupcat2( const wchar_t *a, ... )
 {
-	c2++;
-	
 	int len=wcslen(a);
 	int pos;
 	va_list va, va2;

complete.c

@@ -209,6 +209,9 @@ static hash_table_t *condition_cache=0;
 */
 static hash_table_t *loaded_completions=0;
 
+/**
+   String buffer used by complete_get_desc
+*/
 static string_buffer_t *get_desc_buff=0;
 
 

event.c

@@ -155,7 +155,9 @@ static event_t *event_copy( event_t *event, int copy_arguments )
 	return e;
 }
 
-
+/**
+   Test if specified event is blocked
+*/
 static int event_is_blocked( event_t *e )
 {
 	block_t *block;

event.h

@@ -112,7 +112,6 @@ int event_get( event_t *criterion, array_list_t *out );
    dispatched.
 
    \param event the specific event whose handlers should fire
-   \param arguments the argument string to send to the event handler function
 */
 void event_fire( event_t *event );
 

exec.c

@@ -385,7 +385,7 @@ static int handle_child_io( io_data_t *io, int exit_on_error )
    IO redirections and other file descriptor actions are performed.
 
    \param j the job to set up the IO for
-   \param exit_on_error whether to call exit() on errors
+   \param p the child process to set up
 
    \return 1 on sucess, 0 on failiure
 */

expand.c

@@ -70,12 +70,24 @@ parameter expansion.
 */
 #define COMPLETE_LAST_DESC _( L"Last background job")
 
+/**
+   Error issued on invalid variable name
+*/
 #define COMPLETE_VAR_DESC _( L"The '$' character begins a variable name. The character '%lc', which directly followed a '$', is not allowed as a part of a variable name, and variable names may not be zero characters long. To learn more about variable expansion in fish, type 'help expand-variable'.")
 
+/**
+   Error issued on invalid variable name
+*/
 #define COMPLETE_VAR_NULL_DESC _( L"The '$' begins a variable name. It was given at the end of an argument. Variable names may not be zero characters long. To learn more about variable expansion in fish, type 'help expand-variable'.")
 
+/**
+   Error issued on invalid variable name
+*/
 #define COMPLETE_VAR_BRACKET_DESC _( L"Did you mean {$VARIABLE}? The '$' character begins a variable name. A bracket, which directly followed a '$', is not allowed as a part of a variable name, and variable names may not be zero characters long. To learn more about variable expansion in fish, type 'help expand-variable'." )
 
+/**
+   Error issued on invalid variable name
+*/
 #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'.")
 
 

input.c

@@ -196,7 +196,18 @@ const wchar_t code_arr[] =
 */
 static hash_table_t all_mappings;
 
-static array_list_t *current_mode_mappings, *current_application_mappings, *global_mappings;
+/**
+   Mappings for the current input mode
+*/
+static array_list_t *current_mode_mappings; 
+/**
+   Mappings for the current application
+*/
+static array_list_t *current_application_mappings;
+/**
+   Global mappings
+*/
+static array_list_t *global_mappings;
 
 /**
    Number of nested conditional statement levels that are not evaluated

input.h

@@ -77,8 +77,8 @@ wint_t input_readch();
 /**
    Push a character or a readline function onto the stack of unread
    characters that input_readch will return before actually reading from fd
-   0.
-*/
+   0.   
+ */
 void input_unreadch( wint_t ch );
 
 
@@ -88,7 +88,7 @@ void input_unreadch( wint_t ch );
    \param mode the name of the mapping mode to add this mapping to
    \param s the sequence
    \param d a description of the sequence
-   \param c am input function that will be run whenever the key sequence occurs
+   \param cmd an input function that will be run whenever the key sequence occurs
 */
 void add_mapping( const wchar_t *mode, const wchar_t *s, const wchar_t * d, const wchar_t *cmd );
 

input_common.h

@@ -8,7 +8,7 @@ Header file for the low level input library
 
 #include <wchar.h>
 
-/*
+/**
   Use unencoded private-use keycodes for internal characters
 */
 #define INPUT_COMMON_RESERVED 0xe000
@@ -24,8 +24,14 @@ enum
 }
 	;
 
+/**
+   Init the library
+*/
 void input_common_init( int (*ih)() );
 
+/**
+   Free memory used by the library
+*/
 void input_common_destroy();
 
 /**
@@ -39,6 +45,11 @@ void input_common_destroy();
 */
 wchar_t input_common_readch( int timed );
 
+/**
+   Push a character or a readline function onto the stack of unread
+   characters that input_readch will return before actually reading from fd
+   0.
+*/
 void input_common_unreadch( wint_t ch );
 
 #endif

intern.c

@@ -15,8 +15,15 @@
 #include "common.h"
 #include "intern.h"
 
-hash_table_t *intern_table=0;
-hash_table_t *intern_static_table=0;
+/**
+   Table of interned strings
+*/
+static hash_table_t *intern_table=0;
+
+/**
+   Table of static interned strings
+*/
+static hash_table_t *intern_static_table=0;
 
 /**
    Load static strings that are universally common. Currently only loads the empty string.

mimedb.c

@@ -80,7 +80,7 @@ license. Read the source code of the library for more information.
 */
 #define BUFF_SIZE 1024
 
-/*
+/**
   Program name
 */
 #define MIMEDB "mimedb"
@@ -99,7 +99,14 @@ enum
 }
 ;
 
-static regex_t *start_re=0, *stop_re=0;
+/**
+   Regular expression variable used to find start tag of description
+*/
+static regex_t *start_re=0;
+/**
+   Regular expression variable used to find end tag of description
+*/
+static regex_t *stop_re=0;
 
 /**
    Error flag. Non-zero if something bad happened.
@@ -121,6 +128,9 @@ static int launch_len=0;
 static int launch_pos=0;
 
 #if HAVE_GETTEXT
+/**
+   gettext alias
+*/
 #define _(string) gettext(string)
 #else
 #define _(string) (string)
@@ -477,7 +487,7 @@ static char *get_description( const char *mimetype )
 			start_re = stop_re = 0;
 
 			return 0;
-		}		
+		}
 	}
 	
 	fn_part = my_malloc( strlen(MIME_DIR) + strlen( mimetype) + strlen(MIME_SUFFIX) + 1 );
@@ -1118,7 +1128,9 @@ static void clear_entry( const void *key, const void *val )
 	free( l );
 }
 
-
+/**
+   Do locale specific init
+*/
 static void locale_init()
 {
 	setlocale( LC_ALL, "" );

parser.c

@@ -311,8 +311,10 @@ typedef struct
 	wchar_t *cmd;
 } profile_element_t;
 
-
-int block_count( block_t *b )
+/**
+   Return the current number of block nestings
+*/
+static int block_count( block_t *b )
 {
 		
 	if( b==0)
@@ -449,8 +451,12 @@ const wchar_t *parser_get_block_desc( int block )
 
 }
 
-
-int parser_skip_arguments( const wchar_t *cmd )
+/**
+   Check if the specified bcommand is one of the builtins that cannot
+   have arguments, any followin argument is interpreted as a new
+   command
+*/
+static int parser_skip_arguments( const wchar_t *cmd )
 {
 		
 	return contains_str( cmd,
@@ -459,7 +465,6 @@ int parser_skip_arguments( const wchar_t *cmd )
 						 (void *)0 );
 }
 
-
 int parser_is_subcommand( const wchar_t *cmd )
 {
 	
@@ -506,7 +511,10 @@ int parser_is_reserved( wchar_t *word)
 					  (void *)0 );
 }
 
-int parser_is_pipe_forbidden( wchar_t *word )
+/**
+   Returns 1 if the specified command is a builtin that may not be used in a pipeline
+*/
+static int parser_is_pipe_forbidden( wchar_t *word )
 {
 	return contains_str( word,
 						 L"exec",
@@ -817,9 +825,12 @@ void parser_init()
 	al_init( &forbidden_function );
 }
 
-void print_profile( array_list_t *p, 
-					int pos, 
-					FILE *out )
+/**
+   Print profiling information to the specified stream
+*/
+static void print_profile( array_list_t *p, 
+						   int pos, 
+						   FILE *out )
 {
 	profile_element_t *me, *prev;
 	int i;		

parser.h

@@ -11,6 +11,9 @@
 #include "util.h"
 #include "parser.h"
 
+/**
+   event_block_t represents a block on events of the specified type
+*/
 typedef struct event_block
 {
 	/**
@@ -193,10 +196,10 @@ wchar_t *get_filename( const wchar_t *cmd );
   Evaluate the expressions contained in cmd.
 
   \param cmd the string to evaluate
-  \param out buffer to insert output to. May be null.
-  \param the type of block to push onto the scope stack
+  \param io io redirections to perform on all started jobs
   \param block_type The type of block to push on the block stack
-  \return 0 on success.
+
+  \return 0 on success, 1 otherwise
 */
 int eval( const wchar_t *cmd, io_data_t *io, int block_type );
 
@@ -235,10 +238,10 @@ int parser_is_subcommand( const wchar_t *cmd );
    command scope, like 'for', 'end' or 'command' or 'exec'. These
    functions may not be overloaded, so their names are reserved.
 
-   \param cmd The command name to test
+   \param word The command name to test
    \return 1 of the command parameter is a command, 0 otherwise
 */
-int parser_is_reserved( wchar_t *word);
+int parser_is_reserved( wchar_t *word );
 
 /**
    Returns a string describing the current parser pisition in the format 'FILENAME (line LINE_NUMBER): LINE'.

proc.c

@@ -651,6 +651,9 @@ int job_reap( int interactive )
 
 #ifdef HAVE__PROC_SELF_STAT
 
+/**
+   Maximum length of a /proc/[PID]/stat filename
+*/
 #define FN_SIZE 256
 
 /**
@@ -659,7 +662,6 @@ int job_reap( int interactive )
 unsigned long proc_get_jiffies( process_t *p )
 {
 	wchar_t fn[FN_SIZE];
-	//char stat_line[1024];
 
 	char state;
 	int pid, ppid, pgrp, 

proc.h

@@ -211,6 +211,9 @@ extern job_t *first_job;
 */
 extern int proc_had_barrier;
 
+/**
+   Pid of last process to be started in the background
+*/
 extern pid_t proc_last_bg_pid;
 
 /**
@@ -307,7 +310,7 @@ void proc_sanity_check();
 */
 void proc_fire_event( const wchar_t *msg, int type, pid_t pid, int status );
 
-/*
+/**
   Initializations
 */
 void proc_init();

reader.c

@@ -277,8 +277,16 @@ static struct termios saved_modes;
 */
 static pid_t original_pid;
 
+/**
+   This variable is set to true by the signal handler when ^C is pressed
+*/
 static int interupted=0;
 
+/**
+   Original terminal mode when fish was started
+*/
+static struct termios old_modes;
+
 /*
   Prototypes for a bunch of functions defined later on.
 */
@@ -287,8 +295,10 @@ static void reader_save_status();
 static void reader_check_status();
 static void reader_super_highlight_me_plenty( wchar_t * buff, int *color, int pos, array_list_t *error );
 
-static struct termios old_modes;
 
+/**
+   Give up control of terminal
+*/
 static void term_donate()
 {
 	tcgetattr(0,&old_modes);        /* get the current terminal modes */
@@ -313,6 +323,9 @@ static void term_donate()
 	
 }
 
+/**
+   Grab control of terminal
+*/
 static void term_steal()
 {	
 
@@ -1728,6 +1741,9 @@ void reader_current_subshell_extent( wchar_t **a, wchar_t **b )
 		*b = end;
 }
 
+/**
+   Get the beginning and dend of the job or process definition under the cursor
+*/
 static void reader_current_job_or_process_extent( wchar_t **a, 
 												  wchar_t **b, 
 												  int process )
@@ -1997,6 +2013,9 @@ static int contains( const wchar_t *needle,
 	
 }
 
+/**
+   Reset the data structures associated with the token search
+*/
 static void reset_token_history()
 {
 	wchar_t *begin, *end;

signal.c

@@ -355,6 +355,9 @@ const wchar_t *sig_description( int sig )
 	return L"Unknown";
 }
 
+/**
+   Standard signal handler
+*/
 static void default_handler(int signal, siginfo_t *info, void *context)
 {
 	event_t e;

signal.h

@@ -38,7 +38,7 @@ void signal_set_handlers();
 */
 void signal_handle( int sig, int do_handle );
 
-/*
+/**
   Block all signals
 */
 void signal_block();

tokenizer.c

@@ -54,6 +54,9 @@
 */
 #define FD_STR_MAX_LEN 16
 
+/**
+   Descriptions of all tokenizer errors
+*/
 static const wchar_t *tok_desc[] =
 {
 	N_(L"Tokenizer not yet initialized"),

translate.c

@@ -20,15 +20,34 @@ Translation library, internally uses catgets
 
 #if HAVE_GETTEXT
 
+/**
+   Number of string_buffer_t in the ring of buffers
+*/
 #define BUFF_COUNT 64
 
+/**
+   The ring of string_buffer_t
+*/
 static string_buffer_t buff[BUFF_COUNT];
+/**
+   Current position in the ring
+*/
 static int curr_buff=0;
 
+/**
+   Buffer used by translate_wcs2str
+*/
 static char *wcs2str_buff=0;
+/**
+   Size of buffer used by translate_wcs2str
+*/
 static size_t wcs2str_buff_count=0;
 
-char *translate_wcs2str( const wchar_t *in )
+/**
+   Wide to narrow character conversion. Internal implementation that
+   avoids exessive calls to malloc
+*/
+static char *translate_wcs2str( const wchar_t *in )
 {
 	size_t len = MAX_UTF8_BYTES*wcslen(in)+1;
 	if( len > wcs2str_buff_count )

translate.h

@@ -21,7 +21,9 @@ const wchar_t *wgettext( const wchar_t *in );
 
 /**
   Initialize (or reinitialize) the translation library
-  \param lang The two-character language name, such as 'de' or 'en'
 */
 void translate_init();
+/**
+   Free memory used by the translation library
+*/
 void translate_destroy();

util.h

@@ -450,6 +450,9 @@ int wcsfilecmp( const wchar_t *a, const wchar_t *b );
 */
 void sb_init( string_buffer_t * );
 
+/**
+   Allocate memory for storing a stringbuffer and init it
+*/
 string_buffer_t *sb_new();
 
 /**