changeset 22606:76af23621e19

Better documentation.
author Mark Doliner <mark@kingant.net>
date Thu, 03 Apr 2008 23:51:19 +0000
parents 93c40e412b54
children e09650135f04
files libpurple/buddyicon.c libpurple/buddyicon.h libpurple/imgstore.c libpurple/imgstore.h
diffstat 4 files changed, 19 insertions(+), 10 deletions(-) [+]
line wrap: on
line diff
--- 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
  */
 
--- 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.
--- 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.
  */
--- 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);