# HG changeset patch
# User Mark Doliner <mark@kingant.net>
# Date 1207266679 0
# Node ID 76af23621e1953c8d1900132dc356c2148c241cb
# Parent  93c40e412b54cb433187b8750331a252a3a3c6e6
Better documentation.

diff -r 93c40e412b54 -r 76af23621e19 libpurple/buddyicon.c
--- a/libpurple/buddyicon.c	Thu Apr 03 23:41:57 2008 +0000
+++ b/libpurple/buddyicon.c	Thu Apr 03 23:51:19 2008 +0000
@@ -1,5 +1,5 @@
 /**
- * @file icon.c Buddy Icon API
+ * @file buddyicon.c Buddy Icon API
  * @ingroup core
  */
 
diff -r 93c40e412b54 -r 76af23621e19 libpurple/buddyicon.h
--- a/libpurple/buddyicon.h	Thu Apr 03 23:41:57 2008 +0000
+++ b/libpurple/buddyicon.h	Thu Apr 03 23:51:19 2008 +0000
@@ -45,7 +45,7 @@
 /*@{*/
 
 /**
- * Creates a new buddy icon structure and populate it.
+ * Creates a new buddy icon structure and populates it.
  *
  * If the buddy icon already exists, you'll get a reference to that structure,
  * which will have been updated with the data supplied.
diff -r 93c40e412b54 -r 76af23621e19 libpurple/imgstore.c
--- a/libpurple/imgstore.c	Thu Apr 03 23:41:57 2008 +0000
+++ b/libpurple/imgstore.c	Thu Apr 03 23:51:19 2008 +0000
@@ -36,9 +36,7 @@
 static GHashTable *imgstore;
 static int nextid = 0;
 
-/**
- * Stored image
- *
+/*
  * NOTE: purple_imgstore_add() creates these without zeroing the memory, so
  * NOTE: make sure to update that function when adding members.
  */
diff -r 93c40e412b54 -r 76af23621e19 libpurple/imgstore.h
--- a/libpurple/imgstore.h	Thu Apr 03 23:41:57 2008 +0000
+++ b/libpurple/imgstore.h	Thu Apr 03 23:51:19 2008 +0000
@@ -51,7 +51,11 @@
  *                      ownership of and free as appropriate.  If you want a
  *                      copy of the data, make it before calling this function.
  * @param size		Image data's size.
- * @param filename	Filename associated with image.
+ * @param filename	Filename associated with image.  This is for your
+ *                  convenience.  It could be the full path to the
+ *                  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 The stored image.
  */
@@ -69,9 +73,14 @@
  *                      ownership of and free as appropriate.  If you want a
  *                      copy of the data, make it before calling this function.
  * @param size		Image data's size.
- * @param filename	Filename associated with image.
+ * @param filename	Filename associated with image.  This is for your
+ *                  convenience.  It could be the full path to the
+ *                  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.
+ * @return ID for the image.  This is a unique number that can be used
+ *         within libpurple to reference the image.
  */
 int purple_imgstore_add_with_id(gpointer data, size_t size, const char *filename);
 
@@ -116,11 +125,13 @@
 const char *purple_imgstore_get_filename(const PurpleStoredImage *img);
 
 /**
- * Returns an extension corresponding to the image's file type.
+ * 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.
  *
- * @return The icon's extension or "icon" if unknown.
+ * @return The image's extension (for example "png") or "icon"
+ *         if unknown.
  */
 const char *purple_imgstore_get_extension(PurpleStoredImage *img);