pidgin: b39efaac: Better documentation.

[markdoliner at pidgin.im]

-----------------------------------------------------------------
Revision: b39efaac909bd72f3f2632429caa52ca09aaa583
Ancestor: bae52150c3c1c2f9fd3d1e68a2803acd2346a4c5
Author: markdoliner at pidgin.im
Date: 2008-04-03T23:51:19
Branch: im.pidgin.pidgin
URL: http://d.pidgin.im/viewmtn/revision/info/b39efaac909bd72f3f2632429caa52ca09aaa583

Modified files:
        libpurple/buddyicon.c libpurple/buddyicon.h
        libpurple/imgstore.c libpurple/imgstore.h

ChangeLog: 

Better documentation.

-------------- next part --------------
============================================================
--- libpurple/buddyicon.c	7922224075ec8ab1def9b71134f02d107b4d6db6
+++ libpurple/buddyicon.c	fce4a133a5b955b840c7201afc9352d8e7884f07
@@ -1,5 +1,5 @@
 /**
- * @file icon.c Buddy Icon API
+ * @file buddyicon.c Buddy Icon API
  * @ingroup core
  */
 
============================================================
--- libpurple/buddyicon.h	f6669ada49c9927c080b18190f90939248bbfbfb
+++ libpurple/buddyicon.h	9d6c1ab2905784a1ca86aa264c32f0175621ceaa
@@ -45,7 +45,7 @@ extern "C" {
 /*@{*/
 
 /**
- * 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.
============================================================
--- libpurple/imgstore.c	426640a30426df9ab56993ddafb8ee1cd94a3505
+++ libpurple/imgstore.c	a840c1a905bb7fd407eee461535a6f5bb41b2931
@@ -36,9 +36,7 @@ static int nextid = 0;
 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.
  */
============================================================
--- libpurple/imgstore.h	d44b86d5fb3dcd31cbc7c85684b4f0b8493fe904
+++ libpurple/imgstore.h	74564854a94fae5f2193f766667ebd8e37fefb2f
@@ -51,7 +51,11 @@ extern "C" {
  *                      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 @@ purple_imgstore_add(gpointer data, size_
  *                      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 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);