Improve commenting a bit

darcs-hash:20070924081823-75c98-20dee07adff34f2337c56b30f1e453cc38f40639.gz

common.h

@@ -302,13 +302,14 @@ const wchar_t *wsetlocale( int category, const wchar_t *locale );
 
    \param needle the string to search for in the list 
 
-   \return zero is needle is not found, of if needle is null, non-zero otherwise
+   \return zero if needle is not found, of if needle is null, non-zero otherwise
 */
 __sentinel int contains_str( const wchar_t *needle, ... );
 
 /**
    Call read while blocking the SIGCHLD signal. Should only be called
-   if you _know_ there is data available for reading.
+   if you _know_ there is data available for reading, or the program
+   will hang until there is data.
 */
 int read_blocked(int fd, void *buf, size_t count);
 
@@ -370,17 +371,17 @@ wchar_t *unescape( const wchar_t * in,
 int acquire_lock_file( const char *lockfile, const int timeout, int force );
 
 /** 
-	Returns the width of the terminal window, so that not all
+    Returns the width of the terminal window, so that not all
-	functions that use these values continually have to keep track of
+    functions that use these values continually have to keep track of
-	it.
+    it separately.
 
-   Only works if common_handle_winch is registered to handle winch signals.
+    Only works if common_handle_winch is registered to handle winch signals.
 */
 int common_get_width();
 /**
    Returns the height of the terminal window, so that not all
    functions that use these values continually have to keep track of
-   it.
+   it separatly.
 
    Only works if common_handle_winch is registered to handle winch signals.
 */
@@ -411,9 +412,10 @@ void tokenize_variable_array( const wchar_t *val, array_list_t *out );
 
 
 /**
-   Make sure the specified direcotry exists. If no, try to create it.
+   Make sure the specified direcotry exists. If needed, try to create
+   it and any currently not existing parent directories..
 
-   \return 0 if the directory exists, -1 otherwise.
+   \return 0 if, at the time of function return the directory exists, -1 otherwise.
 */
 int create_directory( wchar_t *d );
 

exec.c

@@ -885,10 +885,13 @@ void exec( job_t *j )
 	signal_block();
 
 	/*
-	  See if we need to create a group keepalive process. This is a
+	  See if we need to create a group keepalive process. This is
-	  process that we create to make sure that the process group
+	  a process that we create to make sure that the process group
-	  doesn't die accidentally, and is needed when a block/function is
+	  doesn't die accidentally, and is often needed when a
-	  inside a pipeline.
+	  builtin/block/function is inside a pipeline, since that
+	  usually means we have to wait for one program to exit before
+	  continuing in the pipeline, causing the group leader to
+	  exit.
 	*/
 	
 	if( job_get_flag( j, JOB_CONTROL ) )
@@ -904,6 +907,7 @@ void exec( job_t *j )
 					break;
 				}
 			}
+			
 		}
 	}