[gegl] Improve introspection annotations for GeglBuffer

[Daniel Sabo <daniels src gnome org>]

commit c36f85bf36b5e9be30bde176e8c2331163b16c2f
Author: Daniel Sabo <DanielSabo gmail com>
Date:   Thu Mar 28 22:34:03 2013 -0700

    Improve introspection annotations for GeglBuffer

 gegl/buffer/gegl-buffer.h |   28 +++++++++++++++-------------
 1 files changed, 15 insertions(+), 13 deletions(-)
---
diff --git a/gegl/buffer/gegl-buffer.h b/gegl/buffer/gegl-buffer.h
index 0d597de..d503aed 100644
--- a/gegl/buffer/gegl-buffer.h
+++ b/gegl/buffer/gegl-buffer.h
@@ -122,13 +122,13 @@ void           gegl_buffer_remove_handler     (GeglBuffer          *buffer,
  * state so multiple instances of gegl can share the same buffer. Sets on
  * one buffer are reflected in the other.
  *
- * Returns: a GeglBuffer object.
+ * Returns: (transfer full): a GeglBuffer object.
  */
 GeglBuffer *    gegl_buffer_open              (const gchar         *path);
 
 /**
  * gegl_buffer_save:
- * @buffer: a #GeglBuffer.
+ * @buffer: (transfer none): a #GeglBuffer.
  * @path: the path where the gegl buffer will be saved, any writable GIO uri is valid.
  * @roi: the region of interest to write, this is the tiles that will be collected and
  * written to disk.
@@ -147,7 +147,7 @@ void            gegl_buffer_save              (GeglBuffer          *buffer,
  * gegl_buffer_save it should be possible to open through any GIO transport, buffers
  * that have been used as swap needs random access to be opened.
  *
- * Returns: a #GeglBuffer object.
+ * Returns: (transfer full): a #GeglBuffer object.
  */
 GeglBuffer *     gegl_buffer_load             (const gchar         *path);
 
@@ -163,10 +163,12 @@ void            gegl_buffer_flush             (GeglBuffer          *buffer);
 
 /**
  * gegl_buffer_create_sub_buffer:
- * @buffer: parent buffer.
- * @extent: coordinates of new buffer.
+ * @buffer: (transfer none): parent buffer.
+ * @extent: (transfer none): coordinates of new buffer.
  *
  * Create a new sub GeglBuffer, that is a view on a larger buffer.
+ *
+ * Return value: (transfer full): the new sub buffer
  */
 GeglBuffer *    gegl_buffer_create_sub_buffer (GeglBuffer          *buffer,
                                                const GeglRectangle *extent);
@@ -382,17 +384,16 @@ void            gegl_buffer_clear             (GeglBuffer          *buffer,
 
 /**
  * gegl_buffer_copy:
- * @src: source buffer.
+ * @src: (transfer none): source buffer.
  * @src_rect: source rectangle (or NULL to copy entire source buffer)
- * @dst: destination buffer.
+ * @dst: (transfer none): destination buffer.
  * @dst_rect: position of upper left destination pixel, or NULL for top
  * left coordinates of the buffer extents.
  *
  * copies a region from source buffer to destination buffer.
  *
  * If the babl_formats of the buffers are the same, and the tile boundaries
- * align, this should optimally lead to shared tiles that are copy on write,
- * this functionality is not implemented yet.
+ * align, this will create copy-on-write tiles in the destination buffer.
  */
 void            gegl_buffer_copy              (GeglBuffer          *src,
                                                const GeglRectangle *src_rect,
@@ -402,11 +403,12 @@ void            gegl_buffer_copy              (GeglBuffer          *src,
 
 /**
  * gegl_buffer_dup:
- * @buffer: the GeglBuffer to duplicate.
+ * @buffer: (transfer none): the GeglBuffer to duplicate.
+ *
+ * Duplicate a buffer (internally uses gegl_buffer_copy). Aligned tiles
+ * will create copy-on-write clones in the new buffer.
  *
- * duplicate a buffer (internally uses gegl_buffer_copy), this should ideally
- * lead to a buffer that shares the raster data with the original on a tile
- * by tile COW basis. This is not yet implemented
+ * Return value: (transfer full): the new buffer
  */
 GeglBuffer *    gegl_buffer_dup               (GeglBuffer       *buffer);