Clarify expectations with error codes like G_IO_ERROR_FAILED

If an error code enumeration is expected to be extended in the future,
people shouldn't compare explicitly against its generic "FAILED" value.

https://bugzilla.gnome.org/show_bug.cgi?id=726775

gio/gioenums.h

@@ -416,7 +416,8 @@ typedef enum {
  */
 /**
  * GIOErrorEnum:
- * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
+ * @G_IO_ERROR_FAILED: Generic error condition for when an operation fails
+ *     and no more specific #GIOErrorEnum value is defined.
  * @G_IO_ERROR_NOT_FOUND: File not found.
  * @G_IO_ERROR_EXISTS: File already exists.
  * @G_IO_ERROR_IS_DIRECTORY: File is a directory.
@@ -472,6 +473,19 @@ typedef enum {
  *
  * Error codes returned by GIO functions.
  *
+ * Note that this domain may be extended in future GLib releases. In
+ * general, new error codes either only apply to new APIs, or else
+ * replace #G_IO_ERROR_FAILED in cases that were not explicitly
+ * distinguished before. You should therefore avoid writing code like
+ * |[<!-- language="C" -->
+ * if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED))
+ *   {
+ *     // Assume that this is EPRINTERONFIRE
+ *     ...
+ *   }
+ * ]|
+ * but should instead treat all unrecognized error codes the same as
+ * #G_IO_ERROR_FAILED.
  **/
 typedef enum {
   G_IO_ERROR_FAILED,

gio/gioerror.c

@@ -44,7 +44,10 @@ G_DEFINE_QUARK (g-io-error-quark, g_io_error)
  * g_io_error_from_errno:
  * @err_no: Error number as defined in errno.h.
  *
- * Converts errno.h error codes into GIO error codes.
+ * Converts errno.h error codes into GIO error codes. The fallback
+ * value %G_IO_ERROR_FAILED is returned for error codes not currently
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
  *
  * Returns: #GIOErrorEnum value for the given errno.h error number.
  **/
@@ -229,9 +232,10 @@ g_io_error_from_errno (gint err_no)
  * g_io_error_from_win32_error:
  * @error_code: Windows error number.
  *
- * Converts some common error codes into GIO error codes. The
+ * Converts some common error codes into GIO error codes. The fallback
- * fallback value G_IO_ERROR_FAILED is returned for error codes not
+ * value %G_IO_ERROR_FAILED is returned for error codes not currently
- * handled.
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
  *
  * Returns: #GIOErrorEnum value for the given error number.
  *

glib/gerror.c

@@ -271,7 +271,11 @@
  * - 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 <NAMESPACE>_<MODULE>_ERROR_FAILED,
- *   for example %G_SPAWN_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:
  *
@@ -502,6 +506,13 @@ g_error_copy (const GError *error)
  * otherwise. In particular, when @error is %NULL, %FALSE will
  * be returned.
  *
+ * 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