/pidgin/main: 901a94245460: Comments: custom smileys

[Tomasz Wasilczyk]

Changeset: 901a942454605fecce8a3e963f3b289dfc17e512
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-05 18:44 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/901a94245460

Description:

Comments: custom smileys

diffstat:

 libpurple/core.c          |   4 ++--
 libpurple/smiley-custom.c |   4 ++--
 libpurple/smiley-custom.h |  47 ++++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 48 insertions(+), 7 deletions(-)

diffs (114 lines):

diff --git a/libpurple/core.c b/libpurple/core.c
--- a/libpurple/core.c
+++ b/libpurple/core.c
@@ -203,7 +203,7 @@ purple_core_init(const char *ui)
 	purple_xfers_init();
 	purple_idle_init();
 	purple_http_init();
-	purple_smiley_custom_init();
+	_purple_smiley_custom_init();
 
 	/*
 	 * Call this early on to try to auto-detect our IP address and
@@ -257,7 +257,7 @@ purple_core_quit(void)
 
 	/* Save .xml files, remove signals, etc. */
 	purple_smiley_theme_uninit();
-	purple_smiley_custom_uninit();
+	_purple_smiley_custom_uninit();
 	purple_http_uninit();
 	purple_idle_uninit();
 	purple_pounces_uninit();
diff --git a/libpurple/smiley-custom.c b/libpurple/smiley-custom.c
--- a/libpurple/smiley-custom.c
+++ b/libpurple/smiley-custom.c
@@ -289,7 +289,7 @@ purple_smiley_custom_get_list(void)
  ******************************************************************************/
 
 void
-purple_smiley_custom_init(void)
+_purple_smiley_custom_init(void)
 {
 	gint ret;
 
@@ -309,7 +309,7 @@ purple_smiley_custom_init(void)
 }
 
 void
-purple_smiley_custom_uninit(void)
+_purple_smiley_custom_uninit(void)
 {
 	g_free(smileys_dir);
 	g_free(smileys_index);
diff --git a/libpurple/smiley-custom.h b/libpurple/smiley-custom.h
--- a/libpurple/smiley-custom.h
+++ b/libpurple/smiley-custom.h
@@ -27,24 +27,65 @@
  * @section_id: libpurple-smiley-custom
  * @short_description: a persistent storage for user-defined smileys
  * @title: Custom smileys storage
+ *
+ * A custom smiley is a non-standard (not defined by a particular protocol)
+ * #PurpleSmiley, defined by user. Some protocols support sending such smileys
+ * for other buddies, that do not have such image on their machine. Protocol
+ * that supports this feature should set the flag
+ * @PURPLE_CONNECTION_FLAG_ALLOW_CUSTOM_SMILEY of #PurpleConnectionFlags.
  */
 
 #include "smiley.h"
 #include "smiley-list.h"
 
+/**
+ * purple_smiley_custom_add:
+ * @image: the smiley's image.
+ * @shortcut: textual representation of a smiley.
+ *
+ * Adds a new smiley to the store. The @shortcut should be unique, but the
+ * @image contents don't have to.
+ *
+ * Returns: a new #PurpleSmiley, or %NULL if error occured.
+ */
 PurpleSmiley *
-purple_smiley_custom_add(PurpleStoredImage *img, const gchar *shortcut);
+purple_smiley_custom_add(PurpleStoredImage *image, const gchar *shortcut);
 
+/**
+ * purple_smiley_custom_remove:
+ * @smiley: the smiley to be removed.
+ *
+ * Removes a @smiley from the store. If the @smiley file is unique (not used by
+ * other smileys) it will be removed from a disk.
+ */
 void
 purple_smiley_custom_remove(PurpleSmiley *smiley);
 
+/**
+ * purple_smiley_custom_get_list:
+ *
+ * Returns the whole list of user-configured custom smileys.
+ *
+ * Returns: a #PurpleSmileyList of custom smileys.
+ */
 PurpleSmileyList *
 purple_smiley_custom_get_list(void);
 
+/**
+ * _purple_smiley_custom_init: (skip)
+ *
+ * Initializes the custom smileys storage subsystem.
+ * Stability: Private
+ */
 void
-purple_smiley_custom_init(void);
+_purple_smiley_custom_init(void);
 
+/**
+ * _purple_smiley_custom_uninit: (skip)
+ *
+ * Uninitializes the custom smileys storage subsystem.
+ */
 void
-purple_smiley_custom_uninit(void);
+_purple_smiley_custom_uninit(void);
 
 #endif /* _PURPLE_SMILEY_CUSTOM_H_ */