cpw.darkrain42.docs: 6ddba69d: Clean up the PurpleSmiley documentation.
paul at darkrain42.org
paul at darkrain42.org
Sun Mar 22 23:10:53 EDT 2009
-----------------------------------------------------------------
Revision: 6ddba69dc6d0bac552c512dd4495b255463c1c5c
Ancestor: 799f7ce56a35bead71cb3a40f6b3d4fa1c273a1c
Author: paul at darkrain42.org
Date: 2009-03-12T05:32:25
Branch: im.pidgin.cpw.darkrain42.docs
URL: http://d.pidgin.im/viewmtn/revision/info/6ddba69dc6d0bac552c512dd4495b255463c1c5c
Modified files:
ChangeLog.API libpurple/smiley.c libpurple/smiley.h
ChangeLog:
Clean up the PurpleSmiley documentation.
Removed references to parameters that don't exist and ref-counting that is
no longer here.
Deprecate purple_smiley_get_storing_dir. It's completely unused. I also
ripped out the smileys_dir from the code and made get_storing_dir return "".
-------------- next part --------------
============================================================
--- ChangeLog.API 360e5fd079d3b227b725ddd06be2c7f1740b3a0b
+++ ChangeLog.API afa04cb443c0ee87022cc7eb89bd5103c85b6743
@@ -30,6 +30,7 @@ version 2.6.0 (??/??/2009):
Deprecated:
* purple_buddy_get_local_alias
* purple_notify_user_info_remove_entry
+ * purple_smiley_get_storing_dir
* purple_status_type_set_primary_attr
* purple_status_type_add_attr
* purple_status_type_add_attrs
============================================================
--- libpurple/smiley.c 525d1524918b111d3d5806f42b9ca54955a5643f
+++ libpurple/smiley.c 514576e7bafc0d208cd85df320dbf5c8cd53b430
@@ -57,9 +57,7 @@ static gboolean smileys_loaded = FALSE;
static guint save_timer = 0;
static gboolean smileys_loaded = FALSE;
-static char *smileys_dir = NULL;
-#define SMILEYS_DEFAULT_FOLDER "custom_smiley"
#define SMILEYS_LOG_ID "smileys"
#define XML_FILE_NAME "smileys.xml"
@@ -872,7 +870,7 @@ purple_smileys_get_storing_dir(void)
const char *
purple_smileys_get_storing_dir(void)
{
- return smileys_dir;
+ return "";
}
void
@@ -881,8 +879,6 @@ purple_smileys_init()
smiley_shortcut_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
smiley_checksum_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
- smileys_dir = g_build_filename(purple_user_dir(), SMILEYS_DEFAULT_FOLDER, NULL);
-
purple_smileys_load();
}
@@ -897,6 +893,5 @@ purple_smileys_uninit()
g_hash_table_destroy(smiley_shortcut_index);
g_hash_table_destroy(smiley_checksum_index);
- g_free(smileys_dir);
}
============================================================
--- libpurple/smiley.h 4902b9db64402a319cdcd8ae154dee876f2b433d
+++ libpurple/smiley.h 415a13181161b926cadaf806a9b125e35c3c3b7a
@@ -61,38 +61,35 @@ extern "C" {
/*@{*/
/**
- * GObject foo.
+ * GObject-fu.
* @internal.
*/
GType purple_smiley_get_type(void);
/**
- * Creates a new custom smiley structure and populates it.
+ * Create 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.
+ * Create 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);
@@ -109,32 +106,28 @@ purple_smiley_delete(PurpleSmiley *smile
* 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.
+ * Changes the custom smiley's image 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.
- *
* @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 @@ const char *purple_smiley_get_checksum(c
* 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 @@ PurpleStoredImage *purple_smiley_get_sto
* 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 @@ const char *purple_smiley_get_extension(
* 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 @@ char *purple_smiley_get_full_path(Purple
/*@{*/
/**
- * 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);
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 @@ purple_smileys_find_by_checksum(const ch
/**
* Returns the directory used to store custom smiley cached files.
*
- * The default directory is PURPLEDIR/smileys, unless otherwise specified
- * by purple_buddy_icons_set_cache_dir().
+ * @return The directory to store custom smyles cached files to.
*
- * @return The directory to store custom smyles cached files to.
+ * @deprecated This function isn't used and does nothing and will be
+ * removed in 3.0.0.
*/
const char *purple_smileys_get_storing_dir(void);
More information about the Commits
mailing list