2008-09-19 Emmanuele Bassi <ebassi@linux.intel.com>

	* clutter/clutter-main.c: Properly document the
	clutter_get_option_group() function and the invariant that
	after parsing Clutter's option group the library will be
	initialized. (Thanks to Tomas Frydrych for pointing this
	out)

diff --git a/ChangeLog b/ChangeLog
index 5920b71..e464f23 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2008-09-19  Emmanuele Bassi  <ebassi@linux.intel.com>
 
+       * clutter/clutter-main.c: Properly document the
+       clutter_get_option_group() function and the invariant that
+       after parsing Clutter's option group the library will be
+       initialized. (Thanks to Tomas Frydrych for pointing this
+       out)
+
+2008-09-19  Emmanuele Bassi  <ebassi@linux.intel.com>
+
        * clutter/x11/clutter-backend-x11.c: Properly document the
        usage of clutter_x11_set_display().
 

diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 00e1242..e6ba2cc 100644 (file)
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -1180,7 +1180,25 @@ post_parse_hook (GOptionContext  *context,
  * g_option_context_add_group(), if you are using g_option_context_parse()
  * to parse your commandline arguments.
  *
- * Return value: a GOptionGroup for the commandline arguments
+ * Calling g_option_context_parse() with Clutter's #GOptionGroup will result
+ * in Clutter's initialization. That is, the following code:
+ *
+ * |[
+ *   g_option_context_set_main_group (context, clutter_get_option_group ());
+ *   res = g_option_context_parse (context, &argc, &argc, NULL);
+ * ]|
+ *
+ * is functionally equivalent to:
+ *
+ * |[
+ *   clutter_init (&argc, &argv);
+ * ]|
+ *
+ * After g_option_context_parse() on a #GOptionContext containing the
+ * Clutter #GOptionGroup has returned %TRUE, Clutter is guaranteed to be
+ * initialized.
+ *
+ * Return value: a #GOptionGroup for the commandline arguments
  *   recognized by Clutter
  *
  * Since: 0.2