/pidgin/main: 8c621fbbee8e: Comments: PidginSmileyTheme

[Tomasz Wasilczyk]

Changeset: 8c621fbbee8e4ea95790dd74cf1724c7942e3da2
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-05 23:13 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/8c621fbbee8e

Description:

Comments: PidginSmileyTheme

diffstat:

 pidgin/gtksmiley-theme.c |  22 +++++-----
 pidgin/gtksmiley-theme.h |  91 +++++++++++++++++++++++++++++++++++++++++++----
 pidgin/libpidgin.c       |   4 +-
 3 files changed, 96 insertions(+), 21 deletions(-)

diffs (216 lines):

diff --git a/pidgin/gtksmiley-theme.c b/pidgin/gtksmiley-theme.c
--- a/pidgin/gtksmiley-theme.c
+++ b/pidgin/gtksmiley-theme.c
@@ -16,7 +16,7 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  */
 
 #include "gtksmiley-theme.h"
@@ -513,8 +513,16 @@ pidgin_smiley_theme_get_smileys_impl(Pur
 	return g_hash_table_lookup(priv->smiley_lists_map, "default");
 }
 
+GList *
+pidgin_smiley_theme_get_all(void)
+{
+	pidgin_smiley_theme_probe();
+
+	return smiley_themes;
+}
+
 void
-pidgin_smiley_theme_init(void)
+_pidgin_smiley_theme_init(void)
 {
 	GList *it;
 	const gchar *user_smileys_dir;
@@ -544,19 +552,11 @@ pidgin_smiley_theme_init(void)
 }
 
 void
-pidgin_smiley_theme_uninit(void)
+_pidgin_smiley_theme_uninit(void)
 {
 	g_strfreev(probe_dirs);
 }
 
-GList *
-pidgin_smiley_theme_get_all(void)
-{
-	pidgin_smiley_theme_probe();
-
-	return smiley_themes;
-}
-
 /*******************************************************************************
  * Object stuff
  ******************************************************************************/
diff --git a/pidgin/gtksmiley-theme.h b/pidgin/gtksmiley-theme.h
--- a/pidgin/gtksmiley-theme.h
+++ b/pidgin/gtksmiley-theme.h
@@ -21,6 +21,15 @@
 
 #ifndef _PIDGIN_SMILEY_THEME_H_
 #define _PIDGIN_SMILEY_THEME_H_
+/**
+ * SECTION:gtksmiley-theme
+ * @include:gtksmiley-theme.h
+ * @section_id: pidgin-smiley-theme
+ * @short_description: a per-protocol categorized sets of standard smileys
+ * @title: Pidgin's smiley themes
+ *
+ * This class implements a per-protocol based #PurpleSmileyTheme.
+ */
 
 #include <glib-object.h>
 #include <gdk-pixbuf/gdk-pixbuf.h>
@@ -41,7 +50,7 @@ typedef struct _PidginSmileyThemeClass P
 /**
  * PidginSmileyTheme:
  *
- * A list of smileys.
+ * An implementation of a smiley theme.
  */
 struct _PidginSmileyTheme
 {
@@ -49,6 +58,11 @@ struct _PidginSmileyTheme
 	PurpleSmileyTheme parent;
 };
 
+/**
+ * PidginSmileyThemeClass:
+ *
+ * Base class for #PidginSmileyTheme objects.
+ */
 struct _PidginSmileyThemeClass
 {
 	/*< private >*/
@@ -65,35 +79,96 @@ G_BEGIN_DECLS
 /**
  * pidgin_smiley_theme_get_type:
  *
- * Returns: The #GType for a smiley list.
+ * Returns: the #GType for a smiley list.
  */
 GType
 pidgin_smiley_theme_get_type(void);
 
+/**
+ * pidgin_smiley_theme_get_name:
+ * @theme: the smiley theme.
+ *
+ * Returns the name for a @theme. Valid themes always have the name set.
+ *
+ * Returns: (transfer none): the name string, or %NULL if error occured.
+ */
 const gchar *
 pidgin_smiley_theme_get_name(PidginSmileyTheme *theme);
 
+/**
+ * pidgin_smiley_theme_get_description:
+ * @theme: the smiley theme.
+ *
+ * Returns the description for a @theme.
+ *
+ * Returns: (transfer none): the description string, or %NULL if it's not
+ *          set or error occured.
+ */
 const gchar *
 pidgin_smiley_theme_get_description(PidginSmileyTheme *theme);
 
+/**
+ * pidgin_smiley_theme_get_icon:
+ * @theme: the smiley theme.
+ *
+ * Returns the @theme's icon image, possibly loading it from the disk (and
+ * adding it to the cache).
+ *
+ * Returns: (transfer none): the @theme's icon image.
+ */
 GdkPixbuf *
 pidgin_smiley_theme_get_icon(PidginSmileyTheme *theme);
 
+/**
+ * pidgin_smiley_theme_get_author:
+ * @theme: the smiley theme.
+ *
+ * Returns the autor of @theme.
+ *
+ * Returns: (transfer none): the author string, or %NULL if it's not
+ *          set or error occured.
+ */
 const gchar *
 pidgin_smiley_theme_get_author(PidginSmileyTheme *theme);
 
+/**
+ * pidgin_smiley_theme_for_conv:
+ * @conv: the conversation.
+ *
+ * Gets the smiley list for a @conv based on current theme.
+ *
+ * Returns: (transfer none): the smiley list, or %NULL if there
+ *          is no smiley theme set.
+ */
 PurpleSmileyList *
 pidgin_smiley_theme_for_conv(PurpleConversation *conv);
 
-void
-pidgin_smiley_theme_init(void);
-
-void
-pidgin_smiley_theme_uninit(void);
-
+/**
+ * pidgin_smiley_theme_get_all:
+ *
+ * Returns the list of currently available smiley themes.
+ *
+ * Returns: (transfer none): the #GList of #PidginSmileyTheme's.
+ */
 GList *
 pidgin_smiley_theme_get_all(void);
 
+/**
+ * _pidgin_smiley_theme_init: (skip)
+ *
+ * Initializes the Pidgin's smiley theme subsystem.
+ */
+void
+_pidgin_smiley_theme_init(void);
+
+/**
+ * _pidgin_smiley_theme_uninit: (skip)
+ *
+ * Unitializes the Pidgin's smiley theme subsystem.
+ */
+void
+_pidgin_smiley_theme_uninit(void);
+
 G_END_DECLS
 
 #endif /* _PIDGIN_SMILEY_THEME_H_ */
diff --git a/pidgin/libpidgin.c b/pidgin/libpidgin.c
--- a/pidgin/libpidgin.c
+++ b/pidgin/libpidgin.c
@@ -283,7 +283,7 @@ pidgin_ui_init(void)
 	pidgin_roomlist_init();
 	pidgin_log_init();
 	pidgin_docklet_init();
-	pidgin_smiley_theme_init();
+	_pidgin_smiley_theme_init();
 	pidgin_utils_init();
 	pidgin_medias_init();
 	pidgin_notify_init();
@@ -302,7 +302,7 @@ pidgin_quit(void)
 	/* Uninit */
 	pidgin_utils_uninit();
 	pidgin_notify_uninit();
-	pidgin_smiley_theme_uninit();
+	_pidgin_smiley_theme_uninit();
 	pidgin_conversations_uninit();
 	pidgin_status_uninit();
 	pidgin_docklet_uninit();