/pidgin/main: d09413e12a04: Better documentation.

[Mark Doliner]

Changeset: d09413e12a04aefe2f230c11dc7a41f8b527be96
Author:	 Mark Doliner <mark at kingant.net>
Date:	 2013-01-21 18:52 -0800
Branch:	 release-2.x.y
URL: http://hg.pidgin.im/pidgin/main/rev/d09413e12a04

Description:

Better documentation.

diffstat:

 libpurple/imgstore.c |  12 +++++++-----
 libpurple/imgstore.h |  25 +++++++++++++++++--------
 2 files changed, 24 insertions(+), 13 deletions(-)

diffs (92 lines):

diff --git a/libpurple/imgstore.c b/libpurple/imgstore.c
--- a/libpurple/imgstore.c
+++ b/libpurple/imgstore.c
@@ -43,9 +43,9 @@ struct _PurpleStoredImage
 {
 	int id;
 	guint8 refcount;
-	size_t size;		/**< The image data's size.	*/
-	char *filename;		/**< The filename (for the UI)	*/
-	gpointer data;		/**< The image data.		*/
+	size_t size;     /**< The image data's size. */
+	char *filename;  /**< The filename (for the UI) */
+	gpointer data;   /**< The image data. */
 };
 
 PurpleStoredImage *
@@ -107,7 +107,8 @@ purple_imgstore_add_with_id(gpointer dat
 	return img->id;
 }
 
-PurpleStoredImage *purple_imgstore_find_by_id(int id) {
+PurpleStoredImage *purple_imgstore_find_by_id(int id)
+{
 	PurpleStoredImage *img = g_hash_table_lookup(imgstore, &id);
 
 	if (img != NULL)
@@ -116,7 +117,8 @@ PurpleStoredImage *purple_imgstore_find_
 	return img;
 }
 
-gconstpointer purple_imgstore_get_data(PurpleStoredImage *img) {
+gconstpointer purple_imgstore_get_data(PurpleStoredImage *img)
+{
 	g_return_val_if_fail(img != NULL, NULL);
 
 	return img->data;
diff --git a/libpurple/imgstore.h b/libpurple/imgstore.h
--- a/libpurple/imgstore.h
+++ b/libpurple/imgstore.h
@@ -39,10 +39,11 @@ extern "C" {
 #endif
 
 /**
- * Add an image to the store.
+ * Create a new PurpleStoredImage.
  *
- * The caller owns a reference to the image in the store, and must dereference
- * the image with purple_imgstore_unref() for it to be freed.
+ * 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.
  *
  * 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.
@@ -57,24 +58,32 @@ extern "C" {
  *                  without any directory information.  It can also be
  *                  NULL, if you don't need to keep track of a filename.
  *
- * @return The stored image.
+ * @return The stored image, or NULL if the image was not added (because of
+ *         empty data or size).
  */
 PurpleStoredImage *
 purple_imgstore_add(gpointer data, size_t size, const char *filename);
 
 /**
- * Create an image and add it to the store.
+ * 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.
  *
  * @param path  The path to the image.
  *
- * @return  The stored image.
- * @since 2.X.X
+ * @return The stored image, or NULL if the image was not added (because of
+ *         empty data or size).
+ *
+ * @since 2.5.0
  */
 PurpleStoredImage *
 purple_imgstore_new_from_file(const char *path);
 
 /**
- * Add an image to the store, allocating an ID.
+ * 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()