[gdk-pixbuf] Various annotation fixes

[Matthias Clasen <matthiasc src gnome org>]

commit d724d378e6483cad1bf095b151f52c850fcb320a
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Dec 16 18:08:33 2011 -0500

    Various annotation fixes
    
    Reported by Evan Nemerson in bug 659888.

 gdk-pixbuf/gdk-pixbuf-core.h   |    7 ++++---
 gdk-pixbuf/gdk-pixbuf-data.c   |    4 ++--
 gdk-pixbuf/gdk-pixbuf-io.c     |   19 +++++++++++--------
 gdk-pixbuf/gdk-pixbuf-loader.c |    4 ++--
 gdk-pixbuf/gdk-pixbuf.c        |    6 +++---
 gdk-pixbuf/gdk-pixdata.c       |   13 ++++++++-----
 gdk-pixbuf/gdk-pixdata.h       |    2 +-
 7 files changed, 31 insertions(+), 24 deletions(-)
---
diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h
index 643f578..1104977 100644
--- a/gdk-pixbuf/gdk-pixbuf-core.h
+++ b/gdk-pixbuf/gdk-pixbuf-core.h
@@ -178,8 +178,9 @@ typedef struct _GdkPixbuf GdkPixbuf;
 
 /**
  * GdkPixbufDestroyNotify:
- * @pixels: The pixel array of the pixbuf that is being finalized.
- * @data: User closure data.
+ * @pixels: (array) (element-type guint8): The pixel array of the pixbuf
+ *   that is being finalized.
+ * @data: (closure): User closure data.
  * 
  * A function of this type is responsible for freeing the pixel array
  * of a pixbuf.  The gdk_pixbuf_new_from_data() function lets you
@@ -345,7 +346,7 @@ gboolean gdk_pixbuf_savev          (GdkPixbuf  *pixbuf,
 
 /**
  * GdkPixbufSaveFunc:
- * @buf: bytes to be written.
+ * @buf: (array length=count) (element-type guint8): bytes to be written.
  * @count: number of bytes in @buf. 
  * @error: (out): A location to return an error.
  * @data: (closure): user data passed to gdk_pixbuf_save_to_callback(). 
diff --git a/gdk-pixbuf/gdk-pixbuf-data.c b/gdk-pixbuf/gdk-pixbuf-data.c
index 2951e13..a9334e8 100644
--- a/gdk-pixbuf/gdk-pixbuf-data.c
+++ b/gdk-pixbuf/gdk-pixbuf-data.c
@@ -30,14 +30,14 @@
 
 /**
  * gdk_pixbuf_new_from_data:
- * @data: (array) (element-type char): Image data in 8-bit/sample packed format
+ * @data: (array): Image data in 8-bit/sample packed format
  * @colorspace: Colorspace for the image data
  * @has_alpha: Whether the data has an opacity channel
  * @bits_per_sample: Number of bits per sample
  * @width: Width of the image in pixels, must be > 0
  * @height: Height of the image in pixels, must be > 0
  * @rowstride: Distance in bytes between row starts
- * @destroy_fn: (scope async): Function used to free the data when the pixbuf's reference count
+ * @destroy_fn: (scope async) (allow-none): Function used to free the data when the pixbuf's reference count
  * drops to zero, or %NULL if the data should not be freed
  * @destroy_fn_data: (closure): Closure data to pass to the destroy notification function
  * 
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 1aae318..649e465 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -1740,14 +1740,15 @@ info_cb (GdkPixbufLoader *loader,
 /**
  * gdk_pixbuf_get_file_info:
  * @filename: The name of the file to identify.
- * @width: Return location for the width of the image, or %NULL
- * @height: Return location for the height of the image, or %NULL
+ * @width: (out): Return location for the width of the image, or %NULL
+ * @height: (out): Return location for the height of the image, or %NULL
  * 
  * Parses an image file far enough to determine its format and size.
  * 
- * Returns: A #GdkPixbufFormat describing the image format of the file 
- *    or %NULL if the image format wasn't recognized. The return value 
- *    is owned by GdkPixbuf and should not be freed.
+ * Returns: (transfer none): A #GdkPixbufFormat describing the image
+ *    format of the file or %NULL if the image format wasn't
+ *    recognized. The return value is owned by GdkPixbuf and should
+ *    not be freed.
  *
  * Since: 2.4
  **/
@@ -2399,7 +2400,7 @@ gdk_pixbuf_save_to_callback    (GdkPixbuf  *pixbuf,
  * @pixbuf: a #GdkPixbuf.
  * @save_func: (scope call): a function that is called to save each block of data that
  *   the save routine generates.
- * @user_data: (closure save_func): user data to pass to the save function.
+ * @user_data: (closure): user data to pass to the save function.
  * @type: name of file format.
  * @option_keys: (array zero-terminated=1) (element-type utf8): name of options to set, %NULL-terminated
  * @option_values: (array zero-terminated=1) (element-type utf8): values for named options
@@ -2445,7 +2446,8 @@ gdk_pixbuf_save_to_callbackv   (GdkPixbuf  *pixbuf,
 /**
  * gdk_pixbuf_save_to_buffer:
  * @pixbuf: a #GdkPixbuf.
- * @buffer: location to receive a pointer to the new buffer.
+ * @buffer: (array length=buffer_size): location to receive a pointer
+ *   to the new buffer.
  * @buffer_size: location to receive the size of the new buffer.
  * @type: name of file format.
  * @error: (allow-none): return location for error, or %NULL
@@ -2532,7 +2534,8 @@ save_to_buffer_callback (const gchar *data,
 /**
  * gdk_pixbuf_save_to_bufferv:
  * @pixbuf: a #GdkPixbuf.
- * @buffer: location to receive a pointer to the new buffer.
+ * @buffer: (array length=buffer_size) (out) (element-type guint8):
+ *   location to receive a pointer to the new buffer.
  * @buffer_size: location to receive the size of the new buffer.
  * @type: name of file format.
  * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 2c9b86f..c2d2d90 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -827,8 +827,8 @@ gdk_pixbuf_loader_close (GdkPixbufLoader *loader,
  * Obtains the available information about the format of the 
  * currently loading image file.
  *
- * Returns: A #GdkPixbufFormat or %NULL. The return value is owned 
- * by GdkPixbuf and should not be freed.
+ * Returns: (transfer none): A #GdkPixbufFormat or %NULL. The return
+ * value is owned by GdkPixbuf and should not be freed.
  * 
  * Since: 2.2
  */
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index b5e6e42..284ab32 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -527,9 +527,9 @@ gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf)
  *
  * Queries a pointer to the pixel data of a pixbuf.
  *
- * Return value: A pointer to the pixbuf's pixel data.  Please see <xref linkend="image-data"/>
- * for information about how the pixel data is stored in
- * memory.
+ * Return value: (array): A pointer to the pixbuf's pixel data.
+ * Please see <xref linkend="image-data"/> for information about how
+ * the pixel data is stored in memory.
  **/
 guchar *
 gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf)
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index 162c71e..8680229 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -101,8 +101,9 @@ pixdata_get_length (const GdkPixdata *pixdata)
  * #GdkPixdata fields in network byte order, plus the @pixel_data
  * bytes the structure points to.
  *
- * Return value: A newly-allocated string containing the serialized
- * #GdkPixdata structure.
+ * Return value: (array length=stream_length_p) (transfer full): A
+ * newly-allocated string containing the serialized #GdkPixdata
+ * structure.
  **/
 guint8* /* free result */
 gdk_pixdata_serialize (const GdkPixdata *pixdata,
@@ -181,7 +182,8 @@ get_uint32 (const guint8 *stream, guint *result)
  * gdk_pixdata_deserialize:
  * @pixdata: a #GdkPixdata structure to be filled in.
  * @stream_length: length of the stream used for deserialization.
- * @stream: stream of bytes containing a serialized #GdkPixdata structure.
+ * @stream: (array length=stream_length): stream of bytes containing a
+ *   serialized #GdkPixdata structure.
  * @error: #GError location to indicate failures (maybe %NULL to ignore errors).
  *
  * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream.
@@ -408,7 +410,7 @@ gdk_pixdata_from_pixbuf (GdkPixdata      *pixdata,
  * if the pixel data is run-length-encoded, the pixel data is copied into
  * newly-allocated memory; otherwise it is reused.
  *
- * Returns: a new #GdkPixbuf.
+ * Returns: (transfer full): a new #GdkPixbuf.
  **/
 GdkPixbuf*
 gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
@@ -853,7 +855,8 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
  * gdk_pixbuf_new_from_inline:
  * @data_length: Length in bytes of the @data argument or -1 to 
  *    disable length checks
- * @data: Byte data containing a serialized #GdkPixdata structure
+ * @data: (array length=data_length): Byte data containing a
+ *    serialized #GdkPixdata structure
  * @copy_pixels: Whether to copy the pixel data, or use direct pointers
  *               @data for the resulting pixbuf
  * @error: #GError return location, may be %NULL to ignore errors
diff --git a/gdk-pixbuf/gdk-pixdata.h b/gdk-pixbuf/gdk-pixdata.h
index eb85034..c217781 100644
--- a/gdk-pixbuf/gdk-pixdata.h
+++ b/gdk-pixbuf/gdk-pixdata.h
@@ -76,7 +76,7 @@ typedef enum
  * @rowstride: Distance in bytes between rows.
  * @width: Width of the image in pixels.
  * @height: Height of the image in pixels.
- * @pixel_data: @width x @height pixels, encoded according to @pixdata_type
+ * @pixel_data: (array) (element-type guint8): @width x @height pixels, encoded according to @pixdata_type
  *   and @rowstride.
  *
  * A #GdkPixdata contains pixbuf information in a form suitable for