[glib] Move documentation to inline comments: spawn

[Javier JardÃn <jjardon src gnome org>]

commit c2dc66ccf2719df9813b0ab97f22af166770f944
Author: Javier JardÃn <jjardon gnome org>
Date:   Wed Jul 6 22:13:05 2011 +0100

    Move documentation to inline comments: spawn

 docs/reference/glib/tmpl/.gitignore |    1 +
 docs/reference/glib/tmpl/spawn.sgml |  198 -----------------------------------
 glib/gspawn.c                       |    9 ++
 glib/gspawn.h                       |   82 ++++++++++++++
 glib/gstring.h                      |   12 ++
 5 files changed, 104 insertions(+), 198 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 69e1543..2d9b777 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -34,6 +34,7 @@ random_numbers.sgml
 relations.sgml
 sequence.sgml
 shell.sgml
+spawn.sgml
 string_chunks.sgml
 thread_pools.sgml
 threads.sgml
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 4eaa33f..7b4f702 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -51,6 +51,15 @@
 #include "gutils.h"
 #include "glibintl.h"
 
+
+/**
+ * SECTION:spawn
+ * @Short_description: process launching
+ * @Title: Spawning Processes
+ */
+
+
+
 static gint g_execute (const gchar  *file,
                        gchar **argv,
                        gchar **envp,
diff --git a/glib/gspawn.h b/glib/gspawn.h
index fa8bfab..c9da1a8 100644
--- a/glib/gspawn.h
+++ b/glib/gspawn.h
@@ -29,9 +29,43 @@
 
 G_BEGIN_DECLS
 
+
 /* I'm not sure I remember our proposed naming convention here. */
+/**
+ * G_SPAWN_ERROR:
+ *
+ * Error domain for spawning processes. Errors in this domain will
+ * be from the #GSpawnError enumeration. See #GError for information on
+ * error domains.
+ */
 #define G_SPAWN_ERROR g_spawn_error_quark ()
 
+/**
+ * GSpawnError:
+ * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
+ * @G_SPAWN_ERROR_READ: Read or select on pipes failed.
+ * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
+ * @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
+ * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
+ * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
+ * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
+ * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
+ * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
+ * @G_SPAWN_ERROR_IO: execv() returned %EIO.
+ * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
+ * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
+ * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
+ * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_FAILED: Some other fatal failure,
+ *   <literal>error-&gt;message</literal> should explain.
+ *
+ * Error codes returned by spawning processes.
+ */
 typedef enum
 {
   G_SPAWN_ERROR_FORK,   /* fork failed due to lack of memory */
@@ -58,8 +92,56 @@ typedef enum
                               */
 } GSpawnError;
 
+/**
+ * GSpawnChildSetupFunc:
+ * @user_data: user data to pass to the function.
+ *
+ * Specifies the type of the setup function passed to g_spawn_async(),
+ * g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
+ * is called in the child after GLib has performed all the setup it plans
+ * to perform but before calling exec(). On POSIX actions taken in this
+ * function will thus only affect the child, not the parent.
+ *
+ * Note that POSIX allows only async-signal-safe functions (see signal(7))
+ * to be called in the child between fork() and exec(), which drastically
+ * limits the usefulness of child setup functions.
+ *
+ * Also note that modifying the environment from the child setup function
+ * may not have the intended effect, since it will get overridden by
+ * a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
+ *
+ * On Windows the function is called in the parent. Its usefulness on
+ * Windows is thus questionable. In many cases executing the child setup
+ * function in the parent can have ill effects, and you should be very
+ * careful when porting software to Windows that uses child setup
+ * functions.
+ */
 typedef void (* GSpawnChildSetupFunc) (gpointer user_data);
 
+/**
+ * GSpawnFlags:
+ * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
+ *   inherited by the child; otherwise all descriptors except stdin/stdout/stderr
+ *   will be closed before calling exec() in the child.
+ * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
+ *   must use g_child_watch_add() yourself (or call waitpid()
+ *   or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
+ * @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
+ *   it will be looked for in the user's <envar>PATH</envar>.
+ * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded,
+ *   instead of going to the same location as the parent's standard output.
+ * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
+ * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
+ *   input (by default, the child's standard input is attached to
+ *   <filename>/dev/null</filename>).
+ * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
+ *   the file to execute, while the remaining elements are the actual argument
+ *   vector to pass to the file. Normally g_spawn_async_with_pipes() uses
+ *   <literal>argv[0]</literal> as the file to execute, and passes all of
+ *   <literal>argv</literal> to the child.
+ *
+ * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
+ */
 typedef enum
 {
   G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0,
diff --git a/glib/gstring.h b/glib/gstring.h
index 2b1dd6e..404fdeb 100644
--- a/glib/gstring.h
+++ b/glib/gstring.h
@@ -40,6 +40,18 @@ G_BEGIN_DECLS
 typedef struct _GString		GString;
 typedef struct _GStringChunk	GStringChunk;
 
+/**
+ * GString:
+ * @str: points to the character data. It may move as text is added.
+ *   The @str field is null-terminated and so
+ *   can be used as an ordinary C string.
+ * @len: contains the length of the string, not including the
+ *   terminating nul byte.
+ * @allocated_len: the number of bytes that can be stored in the
+ *   string before it needs to be reallocated. May be larger than @len.
+ *
+ * The #GString struct contains the public fields of a #GString.
+ */
 struct _GString
 {
   gchar  *str;