docs: Document the behaviour in case of init failure

Or, better, the fact that the behaviour of any Clutter function will be
undefined in case the initialization fails.

The value returned by clutter_init() and friends has to be handled
properly.

diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 7d4d815..f350253 100644 (file)
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -1814,6 +1814,10 @@ clutter_get_option_group_without_init (void)
  * error message will be placed inside @error instead of being
  * printed on the display.
  *
+ * Just like clutter_init(), if this function returns an error code then
+ * any subsequent call to any other Clutter API will result in undefined
+ * behaviour - including segmentation faults.
+ *
  * Return value: %CLUTTER_INIT_SUCCESS if Clutter has been successfully
  *   initialised, or other values or #ClutterInitError in case of
  *   error.
@@ -1951,6 +1955,11 @@ clutter_parse_args (int      *argc,
  * yourself, you can use clutter_init_with_args(), which takes a #GError
  * pointer.</note>
  *
+ * If this function fails, and returns an error code, any subsequent
+ * Clutter API will have undefined behaviour - including segmentation
+ * faults and assertion failures. Make sure to handle the returned
+ * #ClutterInitError enumeration value.
+ *
  * Return value: a #ClutterInitError value
  */
 ClutterInitError