/pidgin/main: bf6e40d37a72: Ever better documentation!

[Mark Doliner]

Changeset: bf6e40d37a72025f46fcb3a199f2f183a162eb43
Author:	 Mark Doliner <mark at kingant.net>
Date:	 2013-01-21 19:56 -0800
Branch:	 release-2.x.y
URL: http://hg.pidgin.im/pidgin/main/rev/bf6e40d37a72

Description:

Ever better documentation!

I don't know why I care so much.

diffstat:

 libpurple/imgstore.h |  38 ++++++++++++++++++++++----------------
 1 files changed, 22 insertions(+), 16 deletions(-)

diffs (105 lines):

diff --git a/libpurple/imgstore.h b/libpurple/imgstore.h
--- a/libpurple/imgstore.h
+++ b/libpurple/imgstore.h
@@ -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 @@ extern "C" {
  * 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 @@ purple_imgstore_add(gpointer data, size_
  * 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 @@ purple_imgstore_new_from_file(const char
  * 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 @@ purple_imgstore_new_from_file(const char
  *                  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 @@ PurpleStoredImage *purple_imgstore_find_
 /**
  * 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 @@ gconstpointer purple_imgstore_get_data(P
 /**
  * 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 @@ size_t purple_imgstore_get_size(PurpleSt
 /**
  * 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 @@ const char *purple_imgstore_get_filename
  * 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.