[cairo-commit] Branch '1.8' - src/cairo-png.c

[Chris Wilson]

 src/cairo-png.c |   17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

New commits:
commit e7d4bc3d864b1b42bb1cae031036ddf6a4445d3c
Author: Chris Wilson <chris at chris-wilson.co.uk>
Date:   Thu Feb 12 10:42:24 2009 +0000

    [png] Correct documentation to avoid reference to NULL
    
    As pointed out by Truc Truong,
    cairo_image_surface_create_from_png_stream() cannot return NULL and so the
    documentation was incorrect.
    
    Fixes http://bugs.freedesktop.org/show_bug.cgi?id=20075
    Bug 20075 There is a misprint in the spec for
    cairo_image_surface_create_from_png_stream() function

diff --git a/src/cairo-png.c b/src/cairo-png.c
index 06e7cb5..93317f3 100644
--- a/src/cairo-png.c
+++ b/src/cairo-png.c
@@ -631,6 +631,10 @@ stdio_read_func (png_structp png, png_bytep data, png_size_t size)
  *	%CAIRO_STATUS_NO_MEMORY
  *	%CAIRO_STATUS_FILE_NOT_FOUND
  *	%CAIRO_STATUS_READ_ERROR
+ *
+ * Alternatively, you can allow errors to propagate through the drawing
+ * operations and check the status on the context upon completion
+ * using cairo_status().
  **/
 cairo_surface_t *
 cairo_image_surface_create_from_png (const char *filename)
@@ -692,8 +696,17 @@ stream_read_func (png_structp png, png_bytep data, png_size_t size)
  * via the @read_func function.
  *
  * Return value: a new #cairo_surface_t initialized with the contents
- * of the PNG file or %NULL if the data read is not a valid PNG image or
- * memory could not be allocated for the operation.
+ * of the PNG file or a "nil" surface if the data read is not a valid PNG image
+ * or memory could not be allocated for the operation.  A nil
+ * surface can be checked for with cairo_surface_status(surface) which
+ * may return one of the following values:
+ *
+ *	%CAIRO_STATUS_NO_MEMORY
+ *	%CAIRO_STATUS_READ_ERROR
+ *
+ * Alternatively, you can allow errors to propagate through the drawing
+ * operations and check the status on the context upon completion
+ * using cairo_status().
  **/
 cairo_surface_t *
 cairo_image_surface_create_from_png_stream (cairo_read_func_t	read_func,