Mercurial > pidgin3 / file diff

--- a/libpurple/imgstore.h	Mon Jan 21 18:52:05 2013 -0800
+++ b/libpurple/imgstore.h	Mon Jan 21 19:56:34 2013 -0800
@@ -29,8 +29,10 @@
 
 #include <glib.h>
 
-/** A reference-counted immutable wrapper around an image's data and its
- *  filename.
+/**
+ * A set of utility functions that provide a reference-counted immutable
+ * wrapper around an image's data and filename.  These functions do not
+ * cache any data to disk.
  */
 typedef struct _PurpleStoredImage PurpleStoredImage;
 
@@ -42,11 +44,11 @@
  * Create a new PurpleStoredImage.
  *
  * Despite the name of this function, the image is NOT added to the image
- * store.  The caller owns a reference to this image and must dereference
- * it with purple_imgstore_unref() for it to be freed.
+ * store and no ID is assigned.  If you need to reference the image by an
+ * ID, use purple_imgstore_add_with_id() instead.
  *
- * No ID is allocated when using this function.  If you need to reference the
- * image by an ID, use purple_imgstore_add_with_id() instead.
+ * The caller owns a reference to this image and must dereference it with
+ * purple_imgstore_unref() for it to be freed.
  *
  * @param data      Pointer to the image data, which the imgstore will take
  *                  ownership of and free as appropriate.  If you want a
@@ -68,8 +70,12 @@
  * Create a PurpleStoredImage using purple_imgstore_add() by reading the
  * given filename from disk.
  *
- * No ID is allocated when using this function.  If you need to reference the
- * image by an ID, use purple_imgstore_add_with_id() instead.
+ * The image is not added to the image store and no ID is assigned.  If you
+ * need to reference the image by an ID, use purple_imgstore_add_with_id()
+ * instead.
+ *
+ * The caller owns a reference to this image and must dereference it with
+ * purple_imgstore_unref() for it to be freed.
  *
  * @param path  The path to the image.
  *
@@ -85,9 +91,9 @@
  * Create a PurpleStoredImage using purple_imgstore_add() and add the
  * image to the image store.  A unique ID will be assigned to the image.
  *
- * The caller owns a reference to the image in the store, and must dereference
- * the image with purple_imgstore_unref_by_id() or purple_imgstore_unref()
- * for it to be freed.
+ * The caller owns a reference to the image and must dereference it with
+ * purple_imgstore_unref() or purple_imgstore_unref_by_id() for it to be
+ * freed.
  *
  * @param data      Pointer to the image data, which the imgstore will take
  *                  ownership of and free as appropriate.  If you want a
@@ -98,7 +104,7 @@
  *                  image or, more commonly, the filename of the image
  *                  without any directory information.  It can also be
  *                  NULL, if you don't need to keep track of a filename.
-
+ *
  * @return ID for the image.  This is a unique number that can be used
  *         within libpurple to reference the image.  0 is returned if the
  *         image was not added (because of empty data or size).
@@ -118,7 +124,7 @@
 /**
  * Retrieves a pointer to the image's data.
  *
- * @param img The Image
+ * @param img The Image.
  *
  * @return A pointer to the data, which must not
  *         be freed or modified.
@@ -128,7 +134,7 @@
 /**
  * Retrieves the length of the image's data.
  *
- * @param img The Image
+ * @param img The Image.
  *
  * @return The size of the data that the pointer returned by
  *         purple_imgstore_get_data points to.
@@ -138,7 +144,7 @@
 /**
  * Retrieves a pointer to the image's filename.
  *
- * @param img The image
+ * @param img The image.
  *
  * @return A pointer to the filename, which must not
  *         be freed or modified.
@@ -149,7 +155,7 @@
  * Looks at the magic numbers of the image data (the first few bytes)
  * and returns an extension corresponding to the image's file type.
  *
- * @param img  The image.
+ * @param img The image.
  *
  * @return The image's extension (for example "png") or "icon"
  *         if unknown.