Fix docs not to talk about %NULL returns. #4271, Duncan Coutts.

1 files changed, 14 insertions, 4 deletions

diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index 3b59a8b37..cc675c064 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -149,8 +149,13 @@ _create_pixman_format (cairo_format_t format)
  * must explicitely clear the buffer, using, for example,
  * cairo_rectangle() and cairo_fill() if you want it cleared.
  *
- * Return value: the newly created surface, or %NULL if it couldn't
- *   be created because of lack of memory
+ * Return value: a pointer to the newly created surface. The caller
+ * owns the surface and should call cairo_surface_destroy when done
+ * with it.
+ *
+ * This function always returns a valid pointer, but it will return a
+ * pointer to a "nil" surface if an error such as out of memory
+ * occurs. You can use cairo_surface_status() to check for this.
  **/
 cairo_surface_t *
 cairo_image_surface_create (cairo_format_t	format,
@@ -203,8 +208,13 @@ cairo_image_surface_create (cairo_format_t	format,
  * must explicitely clear the buffer, using, for example,
  * cairo_rectangle() and cairo_fill() if you want it cleared.
  *
- * Return value: the newly created surface, or %NULL if it couldn't
- *   be created because of lack of memory
+ * Return value: a pointer to the newly created surface. The caller
+ * owns the surface and should call cairo_surface_destroy when done
+ * with it.
+ *
+ * This function always returns a valid pointer, but it will return a
+ * pointer to a "nil" surface if an error such as out of memory
+ * occurs. You can use cairo_surface_status() to check for this.
  **/
 cairo_surface_t *
 cairo_image_surface_create_for_data (unsigned char     *data,