From e555dfc7173897bc0819c715e8897cd1c886e2a3 Mon Sep 17 00:00:00 2001
From: Bryce Harrington <b.harrington@samsung.com>
Date: Wed, 26 Feb 2014 18:42:41 -0800
Subject: [PATCH] Add explanation to _cairo_surface_create_in_error

Patch by Homer Hsing

Bugzilla:  https://bugs.freedesktop.org/show_bug.cgi?id=50413
---
 src/cairo-surface.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index d550131d0..15c3c1310 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -2615,6 +2615,16 @@ _cairo_surface_set_resolution (cairo_surface_t *surface,
     surface->y_resolution = y_res;
 }
 
+/**
+ * _cairo_surface_create_in_error:
+ * @status: the error status
+ *
+ * Return an appropriate static error surface for the error status.
+ * On error, surface creation functions should always return a surface
+ * created with _cairo_surface_create_in_error() instead of a new surface
+ * in an error state. This simplifies internal code as no refcounting has
+ * to be done.
+ **/
 cairo_surface_t *
 _cairo_surface_create_in_error (cairo_status_t status)
 {