diff --git a/ChangeLog b/ChangeLog
index 4f70a8ac4..4b9d58dac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-11-09  Matthias Clasen <mclasen@redhat.com>
+
+	* glib/gspawn.c (g_spawn_sync): Improve the docs.  (#491968,
+	Areg Beketovski)
+
 2007-11-08  Matthias Clasen <mclasen@redhat.com>
 
 	* glib/gmain.c (g_main_context_release): 
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 75eea77ad..e545b4e75 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -191,22 +191,27 @@ read_data (GString *str,
  * @working_directory: child's current working directory, or %NULL to inherit parent's
  * @argv: child's argument vector
  * @envp: child's environment, or %NULL to inherit parent's
- * @flags: flags from #GSpawnFlags
+ * @flags: flags from #GSpawnFlags 
  * @child_setup: function to run in the child just before exec()
  * @user_data: user data for @child_setup
- * @standard_output: return location for child output 
- * @standard_error: return location for child error messages
- * @exit_status: return location for child exit status, as returned by waitpid()
- * @error: return location for error
+ * @standard_output: return location for child output, or %NULL
+ * @standard_error: return location for child error messages, or %NULL
+ * @exit_status: return location for child exit status, as returned by waitpid(), or %NULL
+ * @error: return location for error, or %NULL
  *
  * Executes a child synchronously (waits for the child to exit before returning).
  * All output from the child is stored in @standard_output and @standard_error,
- * if those parameters are non-%NULL. If @exit_status is non-%NULL, the exit 
- * status of the child is stored there as it would be returned by 
- * waitpid(); standard UNIX macros such as WIFEXITED() and WEXITSTATUS() 
- * must be used to evaluate the exit status. If an error occurs, no data is 
- * returned in @standard_output, @standard_error, or @exit_status.
- * 
+ * if those parameters are non-%NULL. Note that you must set the  
+ * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
+ * passing %NULL for @standard_output and @standard_error.
+ * If @exit_status is non-%NULL, the exit status of the child is stored
+ * there as it would be returned by waitpid(); standard UNIX macros such 
+ * as WIFEXITED() and WEXITSTATUS() must be used to evaluate the exit status.
+ * Note that this function call waitpid() even if @exit_status is %NULL, and
+ * does not accept the %G_SPAWN_DO_NOT_REAP_CHILD flag.
+ * If an error occurs, no data is returned in @standard_output, 
+ * @standard_error, or @exit_status. 
+ *
  * This function calls g_spawn_async_with_pipes() internally; see that
  * function for full details on the other parameters and details on
  * how these functions work on Windows.