diff libpurple/smiley.h @ 26760:78ef23551355

merge of '18a763ca3d80ae60e586ade3456b8d59196a7b8f' and '54b44cf23dd4b4d1e79d9c5b04a1496758072127'

--- a/libpurple/smiley.h	Mon Apr 20 00:02:16 2009 +0000
+++ b/libpurple/smiley.h	Mon Apr 20 00:05:54 2009 +0000
@@ -61,44 +61,41 @@
 /*@{*/
 
 /**
- * GObject foo.
+ * GObject-fu.
  * @internal.
  */
 GType purple_smiley_get_type(void);
 
 /**
- * Creates a new custom smiley structure and populates it.
+ * Creates a new custom smiley from a PurpleStoredImage.
  *
- * If a custom smiley with the informed shortcut already exist, it
+ * If a custom smiley with the given shortcut already exists, it
  * will be automaticaly returned.
  *
  * @param img         The image associated with the smiley.
- * @param shortcut    The custom smiley associated shortcut.
+ * @param shortcut    The associated shortcut (e.g. "(homer)").
  *
- * @return The custom smiley structure filled up.
+ * @return The custom smiley.
  */
 PurpleSmiley *
 purple_smiley_new(PurpleStoredImage *img, const char *shortcut);
 
 /**
- * Creates a new custom smiley structure and populates it.
+ * Creates a new custom smiley, reading the image data from a file.
  *
- * The data is retrieved from an already existent file.
- *
- * If a custom smiley with the informed shortcut already exist, it
+ * If a custom smiley with the given shortcut already exists, it
  * will be automaticaly returned.
  *
- * @param shortcut           The custom smiley associated shortcut.
- * @param filepath           The image file to be imported to a
- *                           new custom smiley.
+ * @param shortcut           The associated shortcut (e.g. "(homer)").
+ * @param filepath           The image file.
  *
- * @return The custom smiley structure filled up.
+ * @return The custom smiley.
  */
 PurpleSmiley *
 purple_smiley_new_from_file(const char *shortcut, const char *filepath);
 
 /**
- * Destroy the custom smiley and release the associated resources.
+ * Destroys the custom smiley and release the associated resources.
  *
  * @param smiley    The custom smiley.
  */
@@ -109,32 +106,28 @@
  * Changes the custom smiley's shortcut.
  *
  * @param smiley    The custom smiley.
- * @param shortcut  The custom smiley associated shortcut.
+ * @param shortcut  The new shortcut. A custom smiley with this shortcut
+ *                  cannot already be in use.
  *
- * @return TRUE whether the shortcut is not associated with another
- *         custom smiley and the parameters are valid. FALSE otherwise.
+ * @return TRUE if the shortcut was changed. FALSE otherwise.
  */
 gboolean
 purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut);
 
 /**
- * Changes the custom smiley's data.
- *
- * When the filename controling is made outside this API, the param
- * #keepfilename must be TRUE.
- * Otherwise, the file and filename will be regenerated, and the
- * old one will be removed.
+ * Changes the custom smiley's image data.
  *
  * @param smiley             The custom smiley.
- * @param smiley_data        The custom smiley data.
- * @param smiley_data_len    The custom smiley data length.
+ * @param smiley_data        The custom smiley data, which the smiley code
+ *                           takes ownership of and will free.
+ * @param smiley_data_len    The length of the data in @a smiley_data.
  */
 void
 purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data,
                                            size_t smiley_data_len);
 
 /**
- * Returns the custom smiley's associated shortcut.
+ * Returns the custom smiley's associated shortcut (e.g. "(homer)").
  *
  * @param smiley   The custom smiley.
  *
@@ -155,11 +148,11 @@
  * Returns the PurpleStoredImage with the reference counter incremented.
  *
  * The returned PurpleStoredImage reference counter must be decremented
- * after use.
+ * when the caller is done using it.
  *
  * @param smiley   The custom smiley.
  *
- * @return A PurpleStoredImage reference.
+ * @return A PurpleStoredImage.
  */
 PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley);
 
@@ -167,7 +160,7 @@
  * Returns the custom smiley's data.
  *
  * @param smiley  The custom smiley.
- * @param len     If not @c NULL, the length of the icon data returned
+ * @param len     If not @c NULL, the length of the image data returned
  *                will be set in the location pointed to by this.
  *
  * @return A pointer to the custom smiley data.
@@ -194,6 +187,8 @@
  * directly.  If you find yourself wanting to use this function, think
  * very long and hard about it, and then don't.
  *
+ * Think some more.
+ *
  * @param smiley  The custom smiley.
  *
  * @return A full path to the file, or @c NULL under various conditions.
@@ -210,7 +205,8 @@
 /*@{*/
 
 /**
- * Returns a list of all custom smileys. The caller should free the list.
+ * Returns a list of all custom smileys. The caller is responsible for freeing
+ * the list.
  *
  * @return A list of all custom smileys.
  */
@@ -218,23 +214,21 @@
 purple_smileys_get_all(void);
 
 /**
- * Returns the custom smiley given it's shortcut.
+ * Returns a custom smiley given its shortcut.
  *
  * @param shortcut The custom smiley's shortcut.
  *
- * @return The custom smiley (with a reference for the caller) if found,
- *         or @c NULL if not found.
+ * @return The custom smiley if found, or @c NULL if not found.
  */
 PurpleSmiley *
 purple_smileys_find_by_shortcut(const char *shortcut);
 
 /**
- * Returns the custom smiley given it's checksum.
+ * Returns a custom smiley given its checksum.
  *
  * @param checksum The custom smiley's checksum.
  *
- * @return The custom smiley (with a reference for the caller) if found,
- *         or @c NULL if not found.
+ * @return The custom smiley if found, or @c NULL if not found.
  */
 PurpleSmiley *
 purple_smileys_find_by_checksum(const char *checksum);
@@ -242,10 +236,10 @@
 /**
  * Returns the directory used to store custom smiley cached files.
  *
- * The default directory is PURPLEDIR/smileys, unless otherwise specified
+ * The default directory is PURPLEDIR/custom_smiley, unless otherwise specified
  * by purple_buddy_icons_set_cache_dir().
  *
- * @return The directory to store custom smyles cached files to.
+ * @return The directory in which to store custom smileys cached files.
  */
 const char *purple_smileys_get_storing_dir(void);