Edits to source code comments

darcs-hash:20060608235557-ac50b-052e5c8f2cceb554064d7408573f277275903e7b.gz

builtin.c

@@ -160,16 +160,19 @@ static int count_char( const wchar_t *str, wchar_t c )
 /*
   Here follows the definition of all builtin commands. The function
   names are all on the form builtin_NAME where NAME is the name of the
-  builtin. so the function name for the builtin 'jobs' is
-  'builtin_jobs'.
+  builtin. so the function name for the builtin 'fg' is
+  'builtin_fg'.
 
-  Two builtins, 'command' and 'builtin' are not defined here as they
-  are part of the parser. (They are not parsed as commands, instead
-  they only slightly alter the parser state)
+  A few builtins, including 'while', 'command' and 'builtin' are not
+  defined here as they are handled directly by the parser. (They are
+  not parsed as commands, instead they only alter the parser state)
 
-  If \c b is the buffer representing standard error, and the help
-  message is about to be printed to an interactive screen, it may be
-  shortened to fit the screen.
+  The builtins 'break' and 'continue' are so closely related that they
+  share the same implementation, namely 'builtin_break_continue.
+
+  Several other builtins, including jobs, ulimit and set are so big
+  that they have been given their own file. These files are all named
+  'builtin_NAME.c', where NAME is the name of the builtin.
 
 */
 

builtin.h

@@ -141,6 +141,11 @@ int builtin_count_args( wchar_t **argv );
 /**
    Print help for the specified builtin. If \c b is sb_err, also print
    the line information
+
+   If \c b is the buffer representing standard error, and the help
+   message is about to be printed to an interactive screen, it may be
+   shortened to fit the screen.
+
 */
 void builtin_print_help( wchar_t *cmd, string_buffer_t *b );
 

main.c

@@ -90,9 +90,10 @@ static int read_init()
 
 	if( chdir( cwd ) == -1 )
 	{
-//		fwprintf( stderr, L"Invalid directory: %s\n", cwd );
-//		wperror( L"chdir" );
-//		return 0;
+		/*
+		  If we can't change back to previos irectory, we'll stay in
+		  ~. Should be a sane default behavior.
+		*/
 	}	
 	wcwd = str2wcs( cwd );
 	if( wcwd )

parser.c

@@ -1065,14 +1065,30 @@ void parser_stack_trace( block_t *b, string_buffer_t *buff)
 
 	if( b->type==EVENT )
 	{
+		/*
+		  This is an event handler
+		*/
 		sb_printf( buff, _(L"in event handler: %ls\n"), event_get_desc( b->param1.event ));
 		sb_printf( buff,
 				   L"\n" );
+
+		/*
+		  Stop recursing at event handler. No reason to belive that
+		  any other code is relevant.
+
+		  It might make sense in the future to continue printing the
+		  stack trace of the code that invoked the event, if this is a
+		  programmatic event, but we can't currently detect that.
+		*/
 		return;
 	}
 	
 	if( b->type == FUNCTION_CALL || b->type==SOURCE || b->type==SUBST)
 	{
+		/*
+		  These types of blocks should be printed
+		*/
+
 		int i;
 
 		switch( b->type)
@@ -1129,9 +1145,18 @@ void parser_stack_trace( block_t *b, string_buffer_t *buff)
 		sb_printf( buff,
 				   L"\n" );
 	}
+
+	/*
+	  Recursively print the next block
+	*/
 	parser_stack_trace( b->outer, buff );
 }
 
+/**
+   Returns true if we are currently evaluating a function. This is
+   tested by moving down the block-scope-stack, checking every block
+   if it is of type FUNCTION_CALL.
+*/
 static const wchar_t *is_function()
 {
 	block_t *b = current_block;
@@ -1197,6 +1222,12 @@ const wchar_t *parser_current_filename()
 	}
 }
 
+/**
+   Calculates the on-screen width of the specified substring of the
+   specified string. This function takes into account the width and
+   allignment of the tab character, but other wise behaves like
+   repeatedly calling wcwidth.
+*/
 static int printed_width( const wchar_t *str, int len )
 {
 	int res=0;
@@ -1428,7 +1459,8 @@ static void parse_job_main_loop( process_t *p,
 				tok_next( tok );
 				
 				/*
-				  Don't do anything on failiure. parse_job will notice the error flag beeing set
+				  Don't do anything on failiure. parse_job will notice
+				  the error flag and report any errors for us
 				*/
 				parse_job( p->next, j, tok );
 
@@ -1713,7 +1745,7 @@ static void parse_job_main_loop( process_t *p,
 
 
 /**
-   Fully parse a single job. Does not call exec on it.
+   Fully parse a single job. Does not call exec on it, but any command substitutions in the job will be executed.
 
    \param p The process structure that should be used to represent the first process in the job.
    \param j The job structure to contain the parsed job
@@ -2394,7 +2426,10 @@ static void eval_job( tokenizer *tok )
 			else
 			{
 				/*
-				  This job could not be properly parsed. We free it instead, and set the status to 1.
+				  This job could not be properly parsed. We free it
+				  instead, and set the status to 1. This should be
+				  rare, since most errors should be detected by the
+				  ahead of time validator.
 				*/
 				job_free( j );
 
@@ -2591,6 +2626,9 @@ int eval( const wchar_t *cmd, io_data_t *io, int block_type )
 	return code;
 }
 
+/**
+   \return the block type created by the specified builtin, or -1 on error.
+*/
 static int parser_get_block_type( const wchar_t *cmd )
 {
 	if( wcscmp( cmd, L"while") == 0 )
@@ -2609,7 +2647,11 @@ static int parser_get_block_type( const wchar_t *cmd )
 		return -1;
 }
 
-
+/**
+   Test if this argument contains any errors. Detected errors include
+   syntax errors in command substitutions, imporoper escaped
+   characters and improper use of the variable expansion operator.
+*/
 static int parser_test_argument( const wchar_t *arg, string_buffer_t *out, const wchar_t *prefix, int offset )
 {
 	wchar_t *unesc;