[glibmm] OptionContext: Add API documentation based on the C docs.

[Murray Cumming <murrayc src gnome org>]

commit b4ab89c052d0fb601f6e6f5f00109eb0bab8cbda
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Jan 29 12:05:20 2014 +0100

    OptionContext: Add API documentation based on the C docs.
    
    * glib/src/optioncontext.hg: Add class overview documentation
      based on the C documentation, but reworded to match our C++ API.
      This should now provide some clue about where to start other
      than with our (well hidden) example code.
    * glib/src/optiongroup.hg: Add documentation for the add_entry*()
      methods.

 glib/src/optioncontext.hg |   50 ++++++++++++++++++++++++++++++++++++++++++++-
 glib/src/optionentry.hg   |    1 +
 glib/src/optiongroup.ccg  |    3 +-
 glib/src/optiongroup.hg   |   45 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 97 insertions(+), 2 deletions(-)
---
diff --git a/glib/src/optioncontext.hg b/glib/src/optioncontext.hg
index bc31f15..9747044 100644
--- a/glib/src/optioncontext.hg
+++ b/glib/src/optioncontext.hg
@@ -34,7 +34,55 @@ namespace Glib
  */
 _WRAP_GERROR(OptionError, GOptionError, G_OPTION_ERROR, NO_GTYPE)
 
-/** An OptionContext defines which options are accepted by the commandline option parser.
+/** An OptionContext defines and parses commandline options, using OptionGroup%s and \link OptionEntry 
option entries \endlink.
+ *
+ * It supports short and long commandline options, as shown in the following example:
+ *
+ * <tt>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</tt>
+ *
+ * The example demonstrates a number of features of the GOption
+ * commandline parser
+ * - Options can be single letters, prefixed by a single dash.
+     Multiple short options can be grouped behind a single dash.
+ * - Long options are prefixed by two consecutive dashes.
+ * - 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, which is useful if the extra
+ *   argument starts with a dash, which would otherwise cause it to be
+ *   interpreted as another option.
+ * - Non-option arguments are returned to the application as rest arguments.
+ * - An argument consisting solely of two dashes turns off further parsing,
+ *   any remaining arguments (even those starting with a dash) are returned
+ *   to the application as rest arguments.
+ *
+ * The OptionContext groups options in OptionGroups, 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 OptionContext, and parse all options by a single call
+ * to parse(). See Gtk::Main::add_gtk_option_group(), for an example.
+ *
+ * Add options by creating OptionEntry instances and appropriately-typed variables,
+ * and adding them to an OptionGroup with OptionGroup::add_entry() or 
+ * OptionGroup::add_entry_filename(). The option group should then be added to
+ * the OptionContext with set_main_group() or add_group().
+ *
+ * You might find it convenient to derive your own class from OptionGroup to
+ * contain these OptionEntry instances and member variables.
+ *
+ * If an option is of type string (see OptionGroup::add_entry()) or filename
+ * (see OptionGroup::add_entry_filename()), OptionContext takes
+ * care of converting it to the right encoding. strings are returned in
+ * UTF-8 encoding and filenames are returned in the GLib filename encoding.
+ * Note that this only works if setlocale() has been called before
+ * OptionContext::parse().
+ *
+ * OptionContext can automatically generate nicely formatted help output. Unless it is 
+ * explicitly turned off with set_help_enabled(), this will recognize
+ * the --help, -?, --help-all and --help-groupname options
+ * (where groupname is the name of an OptionGroup) and write suitable text to
+ * stdout.
+ *
+ *
  */
 class OptionContext
 {
diff --git a/glib/src/optionentry.hg b/glib/src/optionentry.hg
index 852dff2..d77eab7 100644
--- a/glib/src/optionentry.hg
+++ b/glib/src/optionentry.hg
@@ -73,6 +73,7 @@ public:
   _MEMBER_SET(short_name, short_name, gchar, gchar)
 
   _MEMBER_GET(flags, flags, int, int)
+
   /** Set one or more OptionEntry::Flags.
    * Do not set FLAG_FILENAME. Character encoding is chosen when the OptionEntry
    * is added to an OptionGroup.
diff --git a/glib/src/optiongroup.ccg b/glib/src/optiongroup.ccg
index d2f81ff..4a87564 100644
--- a/glib/src/optiongroup.ccg
+++ b/glib/src/optiongroup.ccg
@@ -358,7 +358,8 @@ void OptionGroup::add_entry_filename(const OptionEntry& entry, vecstrings& arg)
 // G_OPTION_ARG_STRING_ARRAY, and G_OPTION_ARG_FILENAME_ARRAY, which in glibmm
 // are set by OptionGroup::add_entry[_filename]. But when a callback function
 // is chosen, there is only G_OPTION_ARG_CALLBACK, and the encoding is chosen
-// with G_OPTION_FLAG_FILENAME. Other option flags are set by OptionEntry::set_flags().
+// with G_OPTION_FLAG_FILENAME. We do this automatiically in set_c_arg_default().
+// Other option flags are set by OptionEntry::set_flags().
 
 void OptionGroup::add_entry(const OptionEntry& entry, const SlotOptionArgString& slot)
 {
diff --git a/glib/src/optiongroup.hg b/glib/src/optiongroup.hg
index 7d330eb..9857208 100644
--- a/glib/src/optiongroup.hg
+++ b/glib/src/optiongroup.hg
@@ -83,14 +83,59 @@ public:
   typedef std::vector<Glib::ustring> vecustrings;
   typedef std::vector<std::string> vecstrings;
 
+  /** Add a boolean option @a entry.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   */
   void add_entry(const OptionEntry& entry, bool& arg);
+
+  /** Add an integer option @a entry.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   */
   void add_entry(const OptionEntry& entry, int& arg);
+
+  /** Add a double option @a entry.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   */
   void add_entry(const OptionEntry& entry, double& arg);
+
+  /** Add a UTF-8 string option @a entry.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   *
+   * As indicated by the Glib::ustring type, the string will be
+   * UTF-8 encoded.
+   */
   void add_entry(const OptionEntry& entry, Glib::ustring& arg);
+
+  /** Add a filename string option @a entry.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   *
+   * The string will be in glib's filename encoding.
+   */
   void add_entry_filename(const OptionEntry& entry, std::string& arg);
+
+  /** Add an option @a entry that provides a list of UTF-8 strings.
+   * The @arg parameter will be set to the option's extra argument
+   * after OptionContext::parse() has returned.
+   *
+   * As indicated by the Glib::ustring type, the strings will be
+   * UTF-8 encoded.
+   */
   void add_entry(const OptionEntry& entry, vecustrings& arg);
   void add_entry_filename(const OptionEntry& entry, vecstrings& arg);
+
+  /** Add a string option @a entry, but let a callback slot parse the extra argument
+   * instead of just setting a variable to its value.
+   */
   void add_entry(const OptionEntry& entry, const SlotOptionArgString& slot);
+
+  /** Add a filename option @a entry, but let a callback slot parse the extra argument
+   * instead of just setting a variable to its value.
+   */
   void add_entry_filename(const OptionEntry& entry, const SlotOptionArgFilename& slot);
 
   /** Sets the function which is used to translate user-visible strings, for