Index: src/cairo-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-surface.c,v
retrieving revision 1.94
diff -p -u -6 -r1.94 cairo-surface.c
--- src/cairo-surface.c	19 Aug 2005 19:08:42 -0000	1.94
+++ src/cairo-surface.c	20 Aug 2005 23:14:38 -0000
@@ -542,14 +542,14 @@ cairo_surface_set_device_offset (cairo_s
     surface->device_y_offset = y_offset;
 }
 
 /**
  * _cairo_surface_acquire_source_image:
  * @surface: a #cairo_surface_t
- * @image_out: location to store a pointer to an image surface that includes at least
- *    the intersection of @interest_rect with the visible area of @surface.
+ * @image_out: location to store a pointer to an image surface that includes the
+ *    entire area of @surface.
  *    This surface could be @surface itself, a surface held internal to @surface,
  *    or it could be a new surface with a copy of the relevant portion of @surface.
  * @image_extra: location to store image specific backend data
  * 
  * Gets an image surface to use when drawing as a fallback when drawing with
  * @surface as a source. _cairo_surface_release_source_image() must be called
@@ -569,13 +569,13 @@ _cairo_surface_acquire_source_image (cai
     return surface->backend->acquire_source_image (surface,  image_out, image_extra);
 }
 
 /**
  * _cairo_surface_release_source_image:
  * @surface: a #cairo_surface_t
- * @image_extra: same as return from the matching _cairo_surface_acquire_dest_image()
+ * @image_extra: same as return from the matching _cairo_surface_acquire_source_image()
  * 
  * Releases any resources obtained with _cairo_surface_acquire_source_image()
  **/
 void
 _cairo_surface_release_source_image (cairo_surface_t        *surface,
 				     cairo_image_surface_t  *image,
@@ -600,22 +600,28 @@ _cairo_surface_release_source_image (cai
  *    by the surface stored in @image.
  * @image_extra: location to store image specific backend data
  * 
  * Retrieves a local image for a surface for implementing a fallback drawing
  * operation. After calling this function, the implementation of the fallback
  * drawing operation draws the primitive to the surface stored in @image_out
- * then calls _cairo_surface_release_dest_fallback(),
+ * then calls _cairo_surface_release_dest_image(),
  * which, if a temporary surface was created, copies the bits back to the
  * main surface and frees the temporary surface.
+ *
+ * The surface returned by this function should contain the image bits that
+ * @surface contains in the rectangle. _cairo_surface_release_dest_image should
+ * copy the data back with the equivalent of a SOURCE operator. The returned
+ * image surface should be an ARGB surface if @surface supports destination
+ * alpha, an RGB surface otherwise.
  * 
  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY.
  *  %CAIRO_INT_STATUS_UNSUPPORTED can be returned but this will mean that
  *  the backend can't draw with fallbacks. It's possible for the routine
  *  to store NULL in @local_out and return %CAIRO_STATUS_SUCCESS;
  *  that indicates that no part of @interest_rect is visible, so no drawing
- *  is necessary. _cairo_surface_release_dest_fallback() should not be called in that
+ *  is necessary. _cairo_surface_release_dest_image() should not be called in that
  *  case.
  **/
 cairo_status_t
 _cairo_surface_acquire_dest_image (cairo_surface_t         *surface,
 				   cairo_rectangle_t       *interest_rect,
 				   cairo_image_surface_t  **image_out,
@@ -626,13 +632,13 @@ _cairo_surface_acquire_dest_image (cairo
 
     return surface->backend->acquire_dest_image (surface, interest_rect,
 						 image_out, image_rect, image_extra);
 }
 
 /**
- * _cairo_surface_end_fallback:
+ * _cairo_surface_release_dest_image:
  * @surface: a #cairo_surface_t
  * @interest_rect: same as passed to the matching _cairo_surface_acquire_dest_image()
  * @image: same as returned from the matching _cairo_surface_acquire_dest_image()
  * @image_rect: same as returned from the matching _cairo_surface_acquire_dest_image()
  * @image_extra: same as return from the matching _cairo_surface_acquire_dest_image()
  *