Improve the description of parameter_string in the docs. (#336085, Claudio

2006-03-26  Matthias Clasen  <mclasen@redhat.com>

        * glib/goption.c (g_option_context_new): Improve the description
        of parameter_string in the docs.  (#336085, Claudio Saavedra)

diff --git a/ChangeLog b/ChangeLog
index abb5d28..4eba47c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-03-26  Matthias Clasen  <mclasen@redhat.com>
+
+        * glib/goption.c (g_option_context_new): Improve the description
+        of parameter_string in the docs.  (#336085, Claudio Saavedra)
+
 2006-03-24  Martyn Russell  <martyn@imendio.com>
 
        * glib/gthreadpool.c: Updated the documentation to explain that

diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index abb5d28..4eba47c 100644 (file)
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,3 +1,8 @@
+2006-03-26  Matthias Clasen  <mclasen@redhat.com>
+
+        * glib/goption.c (g_option_context_new): Improve the description
+        of parameter_string in the docs.  (#336085, Claudio Saavedra)
+
 2006-03-24  Martyn Russell  <martyn@imendio.com>
 
        * glib/gthreadpool.c: Updated the documentation to explain that

diff --git a/glib/goption.c b/glib/goption.c
index 73809e6..37a24cd 100644 (file)
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -128,11 +128,27 @@ g_option_error_quark (void)
 /**
  * g_option_context_new:
  * @parameter_string: a string which is displayed in
- *    the first line of <option>--help</option> output, after 
+ *    the first line of <option>--help</option> output, after the
+ *    usage summary 
  *    <literal><replaceable>programname</replaceable> [OPTION...]</literal>
  *
  * Creates a new option context. 
  *
+ * The @parameter_text can serve multiple purposes. It can be used
+ * to add descriptions for "rest" arguments, which are not parsed by
+ * the #GOptionContext, typically something like "FILES" or
+ * "FILE1 FILE2...". (If you are using #G_OPTION_REMAINING for
+ * collecting "rest" arguments, GLib handles this automatically by
+ * using the @arg_description of the corresponding #GOptionEntry in
+ * the usage summary.)
+ *
+ * Another common usage is to give a summary of the program
+ * functionality. This can be a short summary on the same line,  
+ * like " - frob the strings", or a longer description in a paragraph  
+ * below the usage summary. In this case, @parameter_string should start  
+ * with two newlines, to separate the description from the usage summary:  
+ * "\n\nA program to frob strings, which will..."
+ *
  * Returns: a newly created #GOptionContext, which must be
  *    freed with g_option_context_free() after use.
  *