Update todo list and code comments

darcs-hash:20080109012338-75c98-745297861fd11ec82e062a79fe1d15c9084342f1.gz

doc_src/index.hdr.in

@@ -1417,8 +1417,7 @@ g++, javac, java, gcj, lpr, doxygen, whois)
 - Suspending and then resuming pipelines containing a builtin or a shellscript function is broken. Ideally, the exec function in exec.c should be able to resume execution of a partially executed job.
 - delete-word is broken on the commandline 'sudo update-alternatives --config x-'
 - Sometimes autoheader needs to be run on a fresh tarball. Fix dates before creating tarballs.
-- Case insensitive completions don't escape spaces.
+
-- Sometimes case insensitive completions are displayed in the pager even when sensitive completions exist.
 
 If you think you have found a bug not described here, please send a
 report to <a href="mailto:fish-users@lists.sf.net">fish-users@lists.sf.net</a>.

main.c

@@ -106,12 +106,16 @@ 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 )
 {
 	int my_optind;
 	int force_interactive=0;
-	
+		
-	
 	while( 1 )
 	{
 		static struct option
@@ -251,9 +255,17 @@ static int fish_parse_opt( int argc, char **argv, char **cmd_ptr )
 	
 	is_login |= (strcmp( argv[0], "-fish") == 0);
 		
+	/*
+	  We are an interactive session if we have not been given an
+	  explicit command to execute, _and_ stdin is a tty.
+	 */
 	is_interactive_session &= (*cmd_ptr == 0);
 	is_interactive_session &= (my_optind == argc);
 	is_interactive_session &= isatty(STDIN_FILENO);	
+
+	/*
+	  We are also an interactive session if we have are forced-
+	 */
 	is_interactive_session |= force_interactive;
 
 	return my_optind;

proc.c

@@ -488,7 +488,6 @@ void job_handle_signal ( int signal, siginfo_t *info, void *con )
 	got_signal = 1;
 
 //	write( 2, "got signal\n", 11 );
-	
 
 	while(1)
 	{
@@ -846,7 +845,6 @@ static void read_try( job_t *j )
 		if( d->io_mode == IO_BUFFER )
 		{
 			buff=d;
-			
 		}
 	}
 	
@@ -883,6 +881,15 @@ static void read_try( job_t *j )
 }
 
 
+/**
+   Give ownership of the terminal to the specified job. 
+
+   \param j The job to give the terminal to.
+
+   \param cont If this variable is set, we are giving back control to
+   a job that has previously been stopped. In that case, we need to
+   set the terminal attributes to those saved in the job.
+ */
 static int terminal_give_to_job( job_t *j, int cont )
 {
 	
@@ -912,7 +919,9 @@ static int terminal_give_to_job( job_t *j, int cont )
 }
 
 /**
-   Returns contol of the terminal to the shell
+   Returns contol of the terminal to the shell, and saves the terminal
+   attribute state to the job, so that we can restore the terminal
+   ownership to the job at a later time .  
 */
 static int terminal_return_from_job( job_t *j)
 {

proc.h

@@ -229,24 +229,53 @@ typedef struct process
 */
 #define JOB_TERMINAL 256
 
-/** A pipeline of one or more processes. */
+/** 
+    A struct represeting a job. A job is basically a pipeline of one
+    or more processes and a couple of flags.
+ */
 typedef struct job
 {
-	/** command line, used for messages */
+	/** 
+	    The original command which led to the creation of this
+	    job. It is used for displaying messages about job status
+	    on the terminal.
+	*/
 	wchar_t *command;              
-	/** list of processes in this job */
+	
+	/** 
+	    A linked list of all the processes in this job.
+	*/
 	process_t *first_process;  
-	/** process group ID */
+	
+	/** 
+	    process group ID for the process group that this job is
+	    running in. 
+	*/
 	pid_t pgid;   
-	/** saved terminal modes */
+	
-	struct termios tmodes;    
+	/** 
-	/** The job id of the job*/
+	    The saved terminal modes of this job. This needs to be
+	    saved so that we can restore the terminal to the same
+	    state after temporarily taking control over the terminal
+	    when a job stops. 
+	*/
+	struct termios tmodes;
+    
+	/**
+	   The job id of the job. This is a small integer that is a
+	   unique identifier of the job within this shell, and is
+	   used e.g. in process expansion.
+	*/
 	int job_id;
 	
-	/** List of IO redrections for the job */
+	/**
+	   List of all IO redirections for this job 
+	*/
 	io_data_t *io;
 			
-	/** Pointer to the next job */
+	/** 
+	    A pointer to the next job in the job queue 
+	*/
 	struct job *next;           
 
 	/**
@@ -283,21 +312,21 @@ extern int is_interactive_session;
 extern int is_login;
 
 /** 
-	Whether we are a event handler
+	Whether we are running an event handler
 */
 extern int is_event;
 
 /** 
-	Linked list of all jobs 
+	Linked list of all living jobs 
 */
 extern job_t *first_job;   
 
 /**
    Whether a universal variable barrier roundtrip has already been
-   made for this command. Such a roundtrip only needs to be done once
+   made for the currently executing command. Such a roundtrip only
-   on a given command, unless a unversal variable value is
+   needs to be done once on a given command, unless a universal
-   changed. Once this has been done, this variable is set to 1, so
+   variable value is changed. Once this has been done, this variable
-   that no more roundtrips need to be done.
+   is set to 1, so that no more roundtrips need to be done.
 
    Both setting it to one when it should be zero and the opposite may
    cause concurrency bugs.
@@ -310,17 +339,27 @@ extern int proc_had_barrier;
 extern pid_t proc_last_bg_pid;
 
 /**
-   Can be one of JOB_CONTROL_ALL, JOB_CONTROL_INTERACTIVE and JOB_CONTROL_NONE
+   The current job control mode.
+
+   Must be one of JOB_CONTROL_ALL, JOB_CONTROL_INTERACTIVE and JOB_CONTROL_NONE
 */
 extern int job_control_mode;
 
 /**
-   If this flag is set, fish will never fork or run execve.
+   If this flag is set, fish will never fork or run execve. It is used
-*/
+   to put fish into a syntax verifier mode where fish tries to validate
+   the syntax of a file but doesn't actually do anything.
+  */
 extern int no_exec;
 
+/**
+   Add the specified flag to the bitset of flags for the specified job
+ */
 void job_set_flag( job_t *j, int flag, int set );
 
+/**
+   Returns one if the specified flag is set in the specified job, 0 otherwise.
+ */
 int job_get_flag( job_t *j, int flag );
 
 /**