Document GOption

ChangeLog

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/goption.c: Add documentation.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

ChangeLog.pre-2-10

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/goption.c: Add documentation.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

ChangeLog.pre-2-12

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/goption.c: Add documentation.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

ChangeLog.pre-2-6

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/goption.c: Add documentation.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

ChangeLog.pre-2-8

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/goption.c: Add documentation.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2004-10-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/option.sgml: Add docs.
+
 2004-10-28  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/tmpl/keyfile.sgml: Add some introductory notes.

docs/reference/glib/tmpl/option.sgml

@@ -2,11 +2,78 @@
 Commandline option parser
 
 <!-- ##### SECTION Short_Description ##### -->
-
+parses commandline options
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+The GOption commandline parser is intended to be a simpler replacement for the
+popt library. It supports short and long commandline options, as shown in the 
+following example:
+</para>
 
+<para>
+<literal>test -x 1 --long-y foo --flag --long-z=baz -uvw -- file1 file2</literal>
+</para>
+
+<para>
+The example demonstrates a number of features of the GOption commandline parser
+<itemizedlist>
+<listitem><para>
+  Options can be single letters, prefixed by a single dash. Multiple
+  short options can be grouped behind a single dash.
+</para></listitem>
+<listitem><para>
+  Long options are prefixed by two consecutive dashes.
+</para></listitem>
+<listitem><para>
+  Options can have an extra argument, which can be a number, a string or a filename.
+  For long options, the extra argument can be appended with an equals sign after the
+  option name.
+</para></listitem>
+<listitem><para>
+  An argument consisting solely of two dashes turns off further parsing, any remaining
+  arguments are returned to the application as rest arguments.
+</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+Another important feature of GOption is that it can automatically generate nicely
+formatted help output. Unless it is explicitly turned off with 
+g_option_context_set_help_enabled(), GOption will recognize the 
+<option>--help</option>, <option>-?</option>, <option>--help-all</option>
+and <option>--help-</option><replaceable>groupname</replaceable> options (where 
+<replaceable>groupname</replaceable> is the name of a #GOptionGroup) and 
+write a text similar to the one shown in the following example to stdout.
+</para>
+
+<informalexample><screen>
+Usage:
+  testtreemodel [OPTION...]
+
+Help Options:
+  --help                   Show help options
+  --help-all               Show all help options
+  --help-gtk               Show GTK+ Options
+
+Application Options:
+  -r, --repeats=N          Average over N repetitions
+  -m, --max-size=M         Test up to 2^M items
+  --display=DISPLAY        X display to use
+</screen></informalexample>
+
+<para>
+GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
+incorporate options from multiple sources. The intended use for this is
+to let applications collect option groups from the libraries it uses,
+add them to their #GOptionContext, and parse all options by a single call
+to g_option_context_parse(). See gtk_get_option_group() for an example.
+</para>
+
+<para>
+If an option is declared to be of type string or filename, GOption takes
+care of converting it to the right encoding; strings are returned in UTF-8,
+filenames are returned in the GLib filename encoding.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,56 +83,47 @@ Commandline option parser
 
 <!-- ##### ENUM GOptionError ##### -->
 <para>
-
+Error codes returned by option parsing.
 </para>
 
-@G_OPTION_ERROR_UNKNOWN_OPTION: 
+@G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
-@G_OPTION_ERROR_BAD_VALUE: 
+  This error will only be reported, if the parser hasn't been instructed
-@G_OPTION_ERROR_FAILED: 
+  to ignore unknown options, see g_option_context_set_ignore_unknown_options().
+@G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
+@G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
 
 <!-- ##### MACRO G_OPTION_ERROR ##### -->
 <para>
-
+Error domain for option parsing. Errors in this domain will
+be from the #GOptionError enumeration. See #GError for information on 
+error domains.
 </para>
 
 
 
-<!-- ##### ENUM GOptionFlags ##### -->
-<para>
-
-</para>
-
-@G_OPTION_FLAG_HIDDEN: 
-@G_OPTION_FLAG_IN_MAIN: 
-
-<!-- ##### ENUM GOptionArg ##### -->
-<para>
-
-</para>
-
-@G_OPTION_ARG_NONE: 
-@G_OPTION_ARG_STRING: 
-@G_OPTION_ARG_INT: 
-@G_OPTION_ARG_CALLBACK: 
-@G_OPTION_ARG_FILENAME: 
-@G_OPTION_ARG_STRING_ARRAY: 
-@G_OPTION_ARG_FILENAME_ARRAY: 
-
 <!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
 <para>
-
+The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
+options.
 </para>
 
-@option_name: 
+@option_name: The name of the option being parsed. This will be either a 
-@value: 
+  single dash followed by a single letter (for a short name) or two dashes
-@data: 
+  followed by a long option name.
-@error: 
+@value: The value to be parsed.
-@Returns: 
+@data: User data added to the #GOptionGroup containing the option when it
+  was created with g_option_group_new()
+@error: A return location for errors. The error code %G_OPTION_ERROR_FAILED
+  is intended to be used for errors in #GOptionArgFunc callbacks.
+@Returns: %TRUE if the option was successfully parsed, %FALSE if an error 
+  occurred
 
 
 <!-- ##### STRUCT GOptionContext ##### -->
 <para>
-
+A <structname>GOptionContext</structname> struct defines which options
+are accepted by the commandline option parser. The struct has only private 
+fields and should not be directly accessed.
 </para>
 
 
@@ -134,18 +192,87 @@ Commandline option parser
 @Returns: 
 
 
-<!-- ##### STRUCT GOptionEntry ##### -->
+<!-- ##### ENUM GOptionArg ##### -->
 <para>
-
+The #GOptionArg enum values determine which type of extra argument the
+options expect to find. If an option expects an extra argument, it
+can be specified in several ways; with a short option:
+<option>-x arg</option>, with a long option: <option>--name arg</option>
+or combined in a single argument: <option>--name=arg</option>.
 </para>
 
-@long_name: 
+@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
-@short_name: 
+@G_OPTION_ARG_STRING: The option takes a string argument.
-@flags: 
+@G_OPTION_ARG_INT: The option takes an integer argument.
-@arg: 
+@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
-@arg_data: 
+  extra argument.
-@description: 
+@G_OPTION_ARG_FILENAME: The option takes a filename as argument.
-@arg_description: 
+@G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
+  uses of the option are collected into an array of strings.
+@G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, 
+  multiple uses of the option are collected into an array of strings.
+
+<!-- ##### ENUM GOptionFlags ##### -->
+<para>
+Flags which modify individual options.
+</para>
+
+@G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
+   output.
+@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
+   <option>--help</option> output, even if it is defined in a group.
+
+<!-- ##### STRUCT GOptionEntry ##### -->
+<para>
+A <structname>GOptionEntry</structname> defines a single option.
+To have an effect, they must be added to a #GOptionGroup with
+g_option_context_add_main_entries() or g_option_group_add_entries().
+</para>
+
+@long_name: The long name of an option can be used to specify it
+  in a commandline as --<replaceable>long_name</replaceable>. Every
+  option must have a long name.
+@short_name: If an option has a short name, it can be specified
+  -<replaceable>short_name</replaceable> in a commandline.
+@flags: Flags from #GOptionEntryFlags.
+@arg: The type of the option, as a #GOptionArg.
+@arg_data:  If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must 
+ point to a #GOptionArgFunc callback function, which will be called to handle 
+ the extra argument. Otherwise, @arg_data is a pointer to a location to store 
+ the value, the required type of the location depends on the @arg type:
+  <variablelist>
+    <varlistentry>
+      <term>%G_OPTION_ARG_NONE</term>
+      <listitem><para>%gboolean</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>%G_OPTION_ARG_STRING</term>
+      <listitem><para>%gchar*</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>%G_OPTION_ARG_INT</term>
+      <listitem><para>%gint</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>%G_OPTION_ARG_FILENAME</term>
+      <listitem><para>%gchar*</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>%G_OPTION_ARG_STRING_ARRAY</term>
+      <listitem><para>%gchar**</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
+      <listitem><para>%gchar**</para></listitem>
+    </varlistentry>
+  </variablelist>
+@description: the description for the option in <option>--help</option>
+  output. The @description is translated using the @translate_func of the
+  group, see g_option_group_set_translation_domain().
+@arg_description: The placeholder to use for the extra argument parsed
+  by the option in <option>--help</option>
+  output. The @arg_description is translated using the @translate_func of the
+  group, see g_option_group_set_translation_domain().
 
 <!-- ##### FUNCTION g_option_context_add_main_entries ##### -->
 <para>
@@ -159,7 +286,14 @@ Commandline option parser
 
 <!-- ##### STRUCT GOptionGroup ##### -->
 <para>
-
+A <structname>GOptionGroup</structname> struct defines the options in a single
+group. The struct has only private fields and should not be directly accessed. 
+</para>
+<para>
+All options in a group share the same translation function. Libaries which
+need to parse commandline options are expected to provide a function for
+getting a <structname>GOptionGroup</structname> holding their options, which 
+the application can then add to its #GOptionContext.
 </para>
 
 
@@ -222,14 +356,18 @@ Commandline option parser
 
 <!-- ##### USER_FUNCTION GOptionParseFunc ##### -->
 <para>
-
+The type of function that can be called before and after parsing.
 </para>
 
+@context The active #GOptionContext
+
 @context: 
-@group: 
+@group: The group to which the function belongs
-@data: 
+@data: User data added to the #GOptionGroup containing the option when it
-@error: 
+  was created with g_option_group_new()
-@Returns: 
+@error: A return location for error details
+@Returns: %TRUE if the function completed successfully, %FALSE if an error 
+  occurred
 
 
 <!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
@@ -244,13 +382,17 @@ Commandline option parser
 
 <!-- ##### USER_FUNCTION GOptionErrorFunc ##### -->
 <para>
-
+The type of function to be used as callback when a parse error
+occurs.
 </para>
 
+@context The active #GOptionContext
+
 @context: 
-@group: 
+@group: The group to which the function belongs
-@data: 
+@data: User data added to the #GOptionGroup containing the option when it
-@error: 
+  was created with g_option_group_new()
+@error: The #GError containing details about the parse error
 
 
 <!-- ##### FUNCTION g_option_group_set_error_hook ##### -->
@@ -264,12 +406,15 @@ Commandline option parser
 
 <!-- ##### USER_FUNCTION GTranslateFunc ##### -->
 <para>
-
+The type of functions which are used to translate user-visible
+strings, for <option>--help</option> output.
 </para>
 
-@str: 
+@str: the untranslated string
-@data: 
+@data: user data specified when installing the function, e.g.
-@Returns: 
+  in g_option_group_set_translate_func()
+@Returns: a translation of the string for the current locale.
+  The returned string is owned by GLib and must not be freed.
 
 
 <!-- ##### FUNCTION g_option_group_set_translate_func ##### -->

glib/goption.c

@@ -112,6 +112,18 @@ g_option_error_quark (void)
   return q;
 }
 
+/**
+ * g_option_context_new:
+ * @parameter_string: the parameter string to be used in 
+ *    <option>--help</option> output.
+ *
+ * Creates a new option context. 
+ *
+ * Returns: a newly created #GOptionContext, which must be
+ *    freed with g_option_context_free() after use.
+ *
+ * Since: 2.6
+ */
 GOptionContext *
 g_option_context_new (const gchar *parameter_string)
 
@@ -122,13 +134,21 @@ g_option_context_new (const gchar *parameter_string)
 
   context->parameter_string = g_strdup (parameter_string);
   context->help_enabled = TRUE;
+  context->ignore_unknown = FALSE;
 
   return context;
 }
 
-void
+/**
-g_option_context_free (GOptionContext *context)
+ * g_option_context_free:
-{
+ * @context: a #GOptionContext 
+ *
+ * Frees context and all the groups which have been 
+ * added to it.
+ *
+ * Since: 2.6
+ */
+void g_option_context_free (GOptionContext *context) {
 g_return_if_fail (context != NULL);
 
   g_list_foreach (context->groups, (GFunc)g_option_group_free, NULL);
@@ -145,8 +165,21 @@ g_option_context_free (GOptionContext *context)
   g_free (context);
 }
 
-void
+
-g_option_context_set_help_enabled (GOptionContext *context,
+/**
+ * g_option_context_set_help_enabled:
+ * @context: a #GOptionContext
+ * @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it
+ *
+ * Enables or disables automatic generation of <option>--help</option> 
+ * output. By default, g_option_context_parse() recognizes
+ * <option>--help</option>, <option>-?</option>, <option>--help-all</option>
+ * and <option>--help-</option><replaceable>groupname</replaceable> and creates
+ * suitable output to stdout. 
+ *
+ * Since: 2.6
+ */
+void g_option_context_set_help_enabled (GOptionContext *context,
                                         gboolean        help_enabled)
 
 {
@@ -155,6 +188,17 @@ g_option_context_set_help_enabled (GOptionContext *context,
   context->help_enabled = help_enabled;
 }
 
+/**
+ * g_option_context_get_help_enabled:
+ * @context: a #GOptionContext
+ * 
+ * Returns whether automatic <option>--help</option> generation
+ * is turned on for @context. See g_option_context_set_help_enabled().
+ * 
+ * Returns: %TRUE if automatic help generation is turned on.
+ *
+ * Since: 2.6
+ */
 gboolean 
 g_option_context_get_help_enabled (GOptionContext *context) 
 {
@@ -163,6 +207,21 @@ g_option_context_get_help_enabled (GOptionContext *context)
   return context->help_enabled;
 }
 
+/**
+ * g_option_context_set_ignore_unknown_options:
+ * @context: a #GOptionContext
+ * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce
+ *    an error when unknown options are met
+ * 
+ * Sets whether to ignore unknown options or not. If an argument is 
+ * ignored, it is left in the @argv array after parsing. By default, 
+ * g_option_context_parse() treats unknown options as error.
+ * 
+ * This setting does not affect non-option arguments (i.e. arguments 
+ * which don't start with a dash).
+ *
+ * Since: 2.6
+ **/
 void
 g_option_context_set_ignore_unknown_options (GOptionContext *context,
 					     gboolean	     ignore_unknown)
@@ -172,6 +231,17 @@ g_option_context_set_ignore_unknown_options (GOptionContext *context,
   context->ignore_unknown = ignore_unknown;
 }
 
+/**
+ * g_option_context_get_ignore_unknown_options:
+ * @context: a #GOptionContext
+ * 
+ * Returns whether unknown options are ignored or not. See
+ * g_option_context_set_ignore_unknown_options().
+ * 
+ * Returns: %TRUE if unknown options are ignored.
+ * 
+ * Since: 2.6
+ **/
 gboolean
 g_option_context_get_ignore_unknown_options (GOptionContext *context)
 {
@@ -180,6 +250,19 @@ g_option_context_get_ignore_unknown_options (GOptionContext *context)
   return context->ignore_unknown;
 }
 
+/**
+ * g_option_context_add_group:
+ * @context: a #GOptionContext
+ * @group: the group to add
+ * 
+ * Adds a #GOptionGroup to the @context, so that parsing with @context
+ * will recognize the options in the group. Note that the group will
+ * be freed together with the context when g_option_context_free() is
+ * called, so you must not free the group yourself after adding it
+ * to a context.
+ *
+ * Since: 2.6
+ **/
 void
 g_option_context_add_group (GOptionContext *context,
 			    GOptionGroup   *group)
@@ -193,6 +276,18 @@ g_option_context_add_group (GOptionContext *context,
   context->groups = g_list_prepend (context->groups, group);
 }
 
+/**
+ * g_option_context_set_main_group:
+ * @context: a #GOptionContext
+ * @group: the group to set as main group
+ * 
+ * Sets a #GOptionGroup as main group of the @context. 
+ * This has the same effect as calling g_option_context_add_group(), 
+ * the only difference is that the options in the main group are 
+ * treated differently when generating <option>--help</option> output.
+ *
+ * Since: 2.6
+ **/
 void
 g_option_context_set_main_group (GOptionContext *context,
 				 GOptionGroup   *group)
@@ -203,6 +298,18 @@ g_option_context_set_main_group (GOptionContext *context,
   context->main_group = group;
 }
 
+/**
+ * g_option_context_get_main_group:
+ * @context: a #GOptionContext
+ * 
+ * Returns a pointer to the main group of @context.
+ * 
+ * Return value: the main group of @context, or %NULL if @context doesn't
+ *  have a main group. Note that group belongs to @context and should
+ *  not be modified or freed.
+ *
+ * Since: 2.6
+ **/
 GOptionGroup *
 g_option_context_get_main_group (GOptionContext *context)
 {
@@ -211,6 +318,19 @@ g_option_context_get_main_group (GOptionContext *context)
   return context->main_group;
 }
 
+/**
+ * g_option_context_add_main_entries:
+ * @context: a #GOptionContext
+ * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * @translation_domain: a translation domain to use for translating
+ *    the <option>--help</option> output for the options in @entries
+ *    with gettext(), or %NULL
+ * 
+ * A convenience function which creates a main group if it doesn't 
+ * exist, adds the @entries to it and sets the translation domain.
+ * 
+ * Since: 2.6
+ **/
 void
 g_option_context_add_main_entries (GOptionContext      *context,
 				   const GOptionEntry  *entries,
@@ -814,6 +934,28 @@ free_pending_nulls (GOptionContext *context,
   context->pending_nulls = NULL;
 }
 
+/**
+ * g_option_context_parse:
+ * @context: a #GOptionContext
+ * @argc: a pointer to the number of command line arguments.
+ * @argv: a pointer to the array of command line arguments.
+ * @error: a return location for errors 
+ * 
+ * Parses the command line arguments, recognizing options
+ * which have been added to @context. A side-effect of 
+ * calling this function is that g_set_prgname() will be
+ * called.
+ *
+ * If the parsing is successful, any parsed arguments are
+ * removed from the array and @argc and @argv are updated 
+ * accordingly. In case of an error, @argc and @argv are
+ * left unmodified.
+ * 
+ * Return value: %TRUE if the parsing was successful, 
+ *               %FALSE if an error occurred
+ *
+ * Since: 2.6
+ **/
 gboolean
 g_option_context_parse (GOptionContext   *context,
 			gint             *argc,
@@ -1095,7 +1237,27 @@ g_option_context_parse (GOptionContext   *context,
   return FALSE;
 }
 				   
-     
+/**
+ * g_option_group_new:
+ * @name: the name for the option group, this is used to provide
+ *   help for the options in this group with <option>--help-</option>@name
+ * @description: a description for this group to be shown in 
+ *   <option>--help</option>. This string is translated using the translation
+ *   domain or translation function of the group
+ * @help_description: a description for the <option>--help-</option>@name option.
+ *   This string is translated using the translation domain or translation function
+ *   of the group
+ * @user_data: user data that will be passed to the pre- and post-parse hooks,
+ *   the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
+ * @destroy: a function that will be called to free @user_data, or %NULL
+ * 
+ * Creates a new #GOptionGroup.
+ * 
+ * Return value: a newly created option group. It should be added 
+ *   to a #GOptionContext or freed with g_option_group_free().
+ *
+ * Since: 2.6
+ **/
 GOptionGroup *
 g_option_group_new (const gchar    *name,
 		    const gchar    *description,
@@ -1116,6 +1278,15 @@ g_option_group_new (const gchar    *name,
   return group;
 }
 
+/**
+ * g_option_group_free:
+ * @group: a #GOptionGroup
+ * 
+ * Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
+ * free groups which have been added to a #GOptionContext.
+ *
+ * Since: 2.6
+ **/
 void
 g_option_group_free (GOptionGroup *group)
 {
@@ -1137,6 +1308,15 @@ g_option_group_free (GOptionGroup *group)
 }
 
 
+/**
+ * g_option_group_add_entries:
+ * @group: a #GOptionGroup
+ * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * 
+ * Adds the options specified in @entries to @group.
+ *
+ * Since: 2.6
+ **/
 void
 g_option_group_add_entries (GOptionGroup       *group,
 			    const GOptionEntry *entries)
@@ -1154,6 +1334,22 @@ g_option_group_add_entries (GOptionGroup       *group,
   group->n_entries += n_entries;
 }
 
+/**
+ * g_option_group_set_parse_hooks:
+ * @group: a #GOptionGroup
+ * @pre_parse_func: a function to call before parsing, or %NULL
+ * @post_parse_func: a function to call after parsing, or %NULL
+ * 
+ * Associates two functions with @group which will be called 
+ * from g_option_context_parse() before the first option is parsed
+ * and after the last option has been parsed, respectively.
+ *
+ * Note that the user data to be passed to @pre_parse_func and
+ * @post_parse_func can be specified when constructing the group
+ * with g_option_group_new().
+ *
+ * Since: 2.6
+ **/
 void
 g_option_group_set_parse_hooks (GOptionGroup     *group,
 				GOptionParseFunc  pre_parse_func,
@@ -1165,6 +1361,20 @@ g_option_group_set_parse_hooks (GOptionGroup     *group,
   group->post_parse_func = post_parse_func;  
 }
 
+/**
+ * g_option_group_set_error_hook:
+ * @group: a #GOptionGroup
+ * @error_func: a function to call when an error occurs
+ * 
+ * Associates a function with @group which will be called 
+ * from g_option_context_parse() when an error occurs.
+ *
+ * Note that the user data to be passed to @pre_parse_func and
+ * @post_parse_func can be specified when constructing the group
+ * with g_option_group_new().
+ *
+ * Since: 2.6
+ **/
 void
 g_option_group_set_error_hook (GOptionGroup     *group,
 			       GOptionErrorFunc	 error_func)
@@ -1175,11 +1385,28 @@ g_option_group_set_error_hook (GOptionGroup     *group,
 }
 
 
+/**
+ * g_option_group_set_translate_func:
+ * @group: a #GOptionGroup
+ * @func: the #GTranslateFunc, or %NULL 
+ * @data: user data to pass to @func, or %NULL
+ * @destroy_notify: a function which gets called to free @data, or %NULL
+ * 
+ * Sets the function which is used to translate user-visible
+ * strings, for <option>--help</option> output. Different
+ * groups can use different #GTranslateFunc<!-- -->s. If @func
+ * is %NULL, strings are not translated.
+ *
+ * If you are using gettext(), you only need to set the translation
+ * domain, see g_option_group_set_translation_domain().
+ *
+ * Since: 2.6
+ **/
 void
 g_option_group_set_translate_func (GOptionGroup   *group,
 				   GTranslateFunc  func,
 				   gpointer        data,
-				   GDestroyNotify  notify)
+				   GDestroyNotify  destroy_notify)
 {
   g_return_if_fail (group != NULL);
   
@@ -1198,6 +1425,16 @@ dgettext_swapped (const gchar *msgid,
   return dgettext (domainname, msgid);
 }
 
+/**
+ * g_option_group_set_translation_domain:
+ * @group: a #GOptionGroup
+ * @domain: the domain to use
+ * 
+ * A convenience function to use gettext() for translating
+ * user-visible strings. 
+ * 
+ * Since: 2.6
+ **/
 void
 g_option_group_set_translation_domain (GOptionGroup *group,
 				       const gchar  *domain)