X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgerror.c;h=4eed58e9b7980d32d3905fc391eb195afacf3b67;hb=0a4ee12c7a9dfc82443133dfb2b18fb411d79f48;hp=fe6bd7426c766f6d976f0c23ad27d06d48dc8a36;hpb=42cf80780b4fbbe9063ed3d962bb13f341757b3f;p=platform%2Fupstream%2Fglib.git

diff --git a/glib/gerror.c b/glib/gerror.c
index fe6bd74..4eed58e 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -53,16 +53,15 @@
  *
  * Functions that can fail take a return location for a #GError as their
  * last argument. For example:
- * |[
+ * |[<!-- language="C" -->
  * gboolean g_file_get_contents (const gchar  *filename,
  *                               gchar       **contents,
  *                               gsize        *length,
  *                               GError      **error);
  * ]|
- * If you pass a non-%NULL value for the <literal>error</literal>
- * argument, it should point to a location where an error can be placed.
- * For example:
- * |[
+ * If you pass a non-%NULL value for the `error` argument, it should
+ * point to a location where an error can be placed. For example:
+ * |[<!-- language="C" -->
  * gchar *contents;
  * GError *err = NULL;
  *
@@ -70,30 +69,32 @@
  * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
  * if (err != NULL)
  *   {
- *     /&ast; Report error to user, and free error &ast;/
+ *     // Report error to user, and free error
  *     g_assert (contents == NULL);
  *     fprintf (stderr, "Unable to read file: %s\n", err->message);
  *     g_error_free (err);
  *   }
  * else
  *   {
- *     /&ast; Use file contents &ast;/
+ *     // Use file contents
  *     g_assert (contents != NULL);
  *   }
  * ]|
- * Note that <literal>err != NULL</literal> in this example is a
- * reliable indicator of whether g_file_get_contents() failed.
- * Additionally, g_file_get_contents() returns a boolean which
+ * Note that `err != NULL` in this example is a reliable indicator
+ * of whether g_file_get_contents() failed. Additionally,
+ * g_file_get_contents() returns a boolean which
  * indicates whether it was successful.
  *
  * Because g_file_get_contents() returns %FALSE on failure, if you
  * are only interested in whether it failed and don't need to display
  * an error message, you can pass %NULL for the @error argument:
- * |[
- * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /&ast; ignore errors &ast;/
- *   /&ast; no error occurred &ast;/ ;
+ * |[<!-- language="C" -->
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
+ *   // no error occurred 
+ *   ;
  * else
- *   /&ast; error &ast;/ ;
+ *   // error
+ *   ;
  * ]|
  *
  * The #GError object contains three fields: @domain indicates the module
@@ -115,7 +116,7 @@
  * want to g_set_error(), then return immediately. g_set_error()
  * does nothing if the error location passed to it is %NULL.
  * Here's an example:
- * |[
+ * |[<!-- language="C" -->
  * gint
  * foo_open_file (GError **error)
  * {
@@ -126,9 +127,9 @@
  *   if (fd < 0)
  *     {
  *       g_set_error (error,
- *                    FOO_ERROR,                 /&ast; error domain &ast;/
- *                    FOO_ERROR_BLAH,            /&ast; error code &ast;/
- *                    "Failed to open file: %s", /&ast; error message format string &ast;/
+ *                    FOO_ERROR,                 // error domain
+ *                    FOO_ERROR_BLAH,            // error code
+ *                    "Failed to open file: %s", // error message format string
  *                    g_strerror (errno));
  *       return -1;
  *     }
@@ -141,7 +142,7 @@
  * function that can report a #GError. If the sub-function indicates
  * fatal errors in some way other than reporting a #GError, such as
  * by returning %TRUE on success, you can simply do the following:
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -149,12 +150,12 @@
  *
  *   if (!sub_function_that_can_fail (err))
  *     {
- *       /&ast; assert that error was set by the sub-function &ast;/
+ *       // assert that error was set by the sub-function
  *       g_assert (err == NULL || *err != NULL);
  *       return FALSE;
  *     }
  *
- *   /&ast; otherwise continue, no error occurred &ast;/
+ *   // otherwise continue, no error occurred
  *   g_assert (err == NULL || *err == NULL);
  * }
  * ]|
@@ -163,7 +164,7 @@
  * reporting a #GError, you need to create a temporary #GError
  * since the passed-in one may be %NULL. g_propagate_error() is
  * intended for use in this case.
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -176,19 +177,18 @@
  *
  *   if (tmp_error != NULL)
  *     {
- *       /&ast; store tmp_error in err, if err != NULL,
- *        &ast; otherwise call g_error_free() on tmp_error
- *        &ast;/
+ *       // store tmp_error in err, if err != NULL,
+ *       // otherwise call g_error_free() on tmp_error
  *       g_propagate_error (err, tmp_error);
  *       return FALSE;
  *     }
  *
- *   /&ast; otherwise continue, no error occurred &ast;/
+ *   // otherwise continue, no error occurred
  * }
  * ]|
  *
  * Error pileups are always a bug. For example, this code is incorrect:
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -215,7 +215,7 @@
  * of handling an error by always doing nothing about it. So the
  * following code is fine, assuming errors in sub_function_that_can_fail()
  * are not fatal to my_function_that_can_fail():
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -223,7 +223,7 @@
  *
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
- *   sub_function_that_can_fail (NULL); /&ast; ignore errors &ast;/
+ *   sub_function_that_can_fail (NULL); // ignore errors
  *
  *   tmp_error = NULL;
  *   other_function_that_can_fail (&tmp_error);
@@ -236,17 +236,17 @@
  * }
  * ]|
  *
- * Note that passing %NULL for the error location ignores errors; it's
- * equivalent to
- * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
- * in C++. It does not mean to leave errors unhandled; it means to
- * handle them by doing nothing.
+ * Note that passing %NULL for the error location ignores errors;
+ * it's equivalent to
+ * `try { sub_function_that_can_fail (); } catch (...) {}`
+ * in C++. It does not mean to leave errors unhandled; it means
+ * to handle them by doing nothing.
  *
  * Error domains and codes are conventionally named as follows:
  *
- * - The error domain is called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR,
+ * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
  *   for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
- *   |[
+ *   |[<!-- language="C" -->
  *   #define G_SPAWN_ERROR g_spawn_error_quark ()
  *
  *   GQuark
@@ -257,21 +257,25 @@
  *   ]|
  *
  * - The quark function for the error domain is called
- *   &lt;namespace&gt;_&lt;module&gt;_error_quark,
+ *   <namespace>_<module>_error_quark,
  *   for example g_spawn_error_quark() or g_thread_error_quark().
  *
  * - The error codes are in an enumeration called
- *   &lt;Namespace&gt;&lt;Module&gt;Error;
- *   for example,#GThreadError or #GSpawnError.
+ *   <Namespace><Module>Error;
+ *   for example, #GThreadError or #GSpawnError.
  *
  * - Members of the error code enumeration are called
- *   &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;,
+ *   <NAMESPACE>_<MODULE>_ERROR_<CODE>,
  *   for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
  *
  * - If there's a "generic" or "unknown" error code for unrecoverable
  *   errors it doesn't make sense to distinguish with specific codes,
- *   it should be called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED,
- *   for example %G_SPAWN_ERROR_FAILED.
+ *   it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
+ *   for example %G_SPAWN_ERROR_FAILED. In the case of error code
+ *   enumerations that may be extended in future releases, you should
+ *   generally not handle this error code explicitly, but should
+ *   instead treat any unrecognized error code as equivalent to
+ *   FAILED.
  *
  * Summary of rules for use of #GError:
  *
@@ -310,9 +314,23 @@
  *   g_set_error() will complain if you pile up errors.
  *
  * - By convention, if you return a boolean value indicating success
- *   then %TRUE means success and %FALSE means failure. If %FALSE is
+ *   then %TRUE means success and %FALSE means failure.
+ *   <footnote><para>Avoid creating functions which have a boolean
+ *   return value and a GError parameter, but where the boolean does
+ *   something other than signal whether the GError is set.  Among other
+ *   problems, it requires C callers to allocate a temporary error.  Instead,
+ *   provide a "gboolean *" out parameter. There are functions in GLib
+ *   itself such as g_key_file_has_key() that are deprecated because of this.
+ *   </para></footnote>
+ *   If %FALSE is
  *   returned, the error must be set to a non-%NULL value.
- * 
+ *   <footnote><para>One exception to this is that in situations that are
+ *   already considered to be undefined behaviour (such as when a
+ *   g_return_val_if_fail() check fails), the error need not be set.
+ *   Instead of checking separately whether the error is set, callers
+ *   should ensure that they do not provoke undefined behaviour, then
+ *   assume that the error will be set on failure.</para></footnote>
+ *
  * - A %NULL return value is also frequently used to mean that an error
  *   occurred. You should make clear in your documentation whether %NULL
  *   is a valid return value in non-error cases; if %NULL is a valid value,
@@ -322,7 +340,7 @@
  * - When implementing a function that can report errors, you may want
  *   to add a check at the top of your function that the error return
  *   location is either %NULL or contains a %NULL error (e.g.
- *   <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
+ *   `g_return_if_fail (error == NULL || *error == NULL);`).
  */
 
 #include "config.h"
@@ -382,7 +400,7 @@ g_error_new_valist (GQuark       domain,
  * Creates a new #GError with the given @domain and @code,
  * and a message formatted with @format.
  *
- * Return value: a new #GError
+ * Returns: a new #GError
  */
 GError*
 g_error_new (GQuark       domain,
@@ -414,7 +432,7 @@ g_error_new (GQuark       domain,
  * @message contains text you don't have control over,
  * that could include printf() escape sequences.
  *
- * Return value: a new #GError
+ * Returns: a new #GError
  **/
 GError*
 g_error_new_literal (GQuark         domain,
@@ -457,7 +475,7 @@ g_error_free (GError *error)
  *
  * Makes a copy of @error.
  *
- * Return value: a new #GError
+ * Returns: a new #GError
  */
 GError*
 g_error_copy (const GError *error)
@@ -488,7 +506,14 @@ g_error_copy (const GError *error)
  * otherwise. In particular, when @error is %NULL, %FALSE will
  * be returned.
  *
- * Return value: whether @error has @domain and @code
+ * If @domain contains a `FAILED` (or otherwise generic) error code,
+ * you should generally not check for it explicitly, but should
+ * instead treat any not-explicitly-recognized error code as being
+ * equilalent to the `FAILED` code. This way, if the domain is
+ * extended in the future to provide a more specific error code for
+ * a certain case, your code will still work.
+ *
+ * Returns: whether @error has @domain and @code
  */
 gboolean
 g_error_matches (const GError *error,
@@ -579,6 +604,10 @@ g_set_error_literal (GError      **err,
  *
  * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
  * The error variable @dest points to must be %NULL.
+ *
+ * Note that @src is no longer valid after this call. If you want
+ * to keep using the same GError*, you need to set it to %NULL
+ * after calling this function on it.
  */
 void
 g_propagate_error (GError **dest,