/dev/tomkiewicz/new-smileys: f29bb25cfbd8: Smileys: fill comment...

Fri Apr 4 21:21:09 EDT 2014

Changeset: f29bb25cfbd8ca0a23f69e39933d3f8c3e8be6d0
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-05 03:12 +0200
Branch:	 default
URL: https://hg.pidgin.im/dev/tomkiewicz/new-smileys/rev/f29bb25cfbd8

Description:

Smileys: fill comments for old files

diffstat:

 libpurple/conversation.h |  33 ++++++++++++++++++++++++++++++++-
 libpurple/imgstore.h     |  12 +++++++++++-
 libpurple/trie.h         |  20 ++++++++++++++++++++
 libpurple/util.h         |  13 ++++++++++++-
 pidgin/gtkutils.h        |  16 ++++++++++++++++
 pidgin/gtkwebview.h      |   7 +++++++
 6 files changed, 98 insertions(+), 3 deletions(-)

diffs (184 lines):

diff --git a/libpurple/conversation.h b/libpurple/conversation.h
--- a/libpurple/conversation.h
+++ b/libpurple/conversation.h
@@ -675,15 +675,46 @@ gboolean purple_conversation_do_command(
 gssize
 purple_conversation_get_max_message_size(PurpleConversation *conv);
 
+/**
+ * purple_conversation_add_remote_smiley:
+ * @conv: The conversation that receives new smiley.
+ * @shortcut: The shortcut for the new smiley.
+ *
+ * Adds new smiley to the list of remote smileys for this conversation.
+ * The smiley have to be written and closed, when data is ready.
+ *
+ * Returns: (transfer none): New smiley, or %NULL if it's already being
+ *          retrieved (or possibly, in case of error).
+ */
 PurpleRemoteSmiley *
 purple_conversation_add_remote_smiley(PurpleConversation *conv,
 	const gchar *shortcut);
 
-/* use it only, if you cannot store purple_conversation_add_remote_smiley output or control its ref */
+/**
+ * purple_conversation_get_remote_smiley:
+ * @conv: The conversation.
+ * @shortcut: The shortcut.
+ *
+ * Lookups for the remote smiley previously added to this conversation.
+ *
+ * You may use this function when you receive the smiley data, but it's
+ * better just to store and use the reference returned by
+ * #purple_conversation_add_remote_smiley.
+ *
+ * Returns: (transfer none): The smiley, or %NULL if it doesn't exists.
+ */
 PurpleRemoteSmiley *
 purple_conversation_get_remote_smiley(PurpleConversation *conv,
 	const gchar *shortcut);
 
+/**
+ * purple_conversation_get_remote_smileys:
+ * @conv: The conversation.
+ *
+ * Get all remote smileys previously added to this conversation.
+ *
+ * Returns: (transfer none): The list of remote smileys.
+ */
 PurpleSmileyList *
 purple_conversation_get_remote_smileys(PurpleConversation *conv);
 
diff --git a/libpurple/imgstore.h b/libpurple/imgstore.h
--- a/libpurple/imgstore.h
+++ b/libpurple/imgstore.h
@@ -47,8 +47,9 @@
 typedef struct _PurpleStoredImage PurpleStoredImage;
 
 #define PURPLE_TYPE_STORED_IMAGE (purple_imgstore_get_type())
+
+/* TODO: make it a real GObject */
 #if 0
-/* TODO */
 #define PURPLE_IS_STORED_IMAGE(image) (G_TYPE_CHECK_INSTANCE_TYPE((image), PURPLE_TYPE_STORED_IMAGE))
 #else
 #define PURPLE_IS_STORED_IMAGE(image) ((image) != NULL)
@@ -148,6 +149,15 @@ purple_imgstore_new_from_file(const char
  */
 int purple_imgstore_new_with_id(gpointer data, size_t size, const char *filename);
 
+/**
+ * purple_imgstore_add_with_id:
+ * @image: The image.
+ *
+ * Adds previously created #PurpleStoredImage to the local store with newly
+ * generated id. If it was already in the store, an old id will be returned.
+ *
+ * Returns: ID for the image.
+ */
 int
 purple_imgstore_add_with_id(PurpleStoredImage *image);
 
diff --git a/libpurple/trie.h b/libpurple/trie.h
--- a/libpurple/trie.h
+++ b/libpurple/trie.h
@@ -138,6 +138,12 @@ purple_trie_add(PurpleTrie *trie, const 
 void
 purple_trie_remove(PurpleTrie *trie, const gchar *word);
 
+/**
+ * purple_trie_get_size:
+ * @trie: The trie.
+ *
+ * Returns: The number of elements stored in this trie.
+ */
 guint
 purple_trie_get_size(PurpleTrie *trie);
 
@@ -177,6 +183,20 @@ gchar *
 purple_trie_multi_replace(const GSList *tries, const gchar *src,
 	PurpleTrieReplaceCb replace_cb, gpointer user_data);
 
+/**
+ * purple_trie_find:
+ * @trie: The trie.
+ * @src: The source string.
+ * @find_cb: The callback for found entries (may be %NULL).
+ * @user_data: Custom data to be passed to @find_cb.
+ *
+ * Processes @src string and finds all occuriences of words added to @trie.
+ * It's O(strlen(src)), if find_cb runs in O(1).
+ *
+ * The word is counted as found if it's found and the callback returns %TRUE.
+ *
+ * Returns: The number of found words.
+ */
 gulong
 purple_trie_find(PurpleTrie *trie, const gchar *src,
 	PurpleTrieFindCb find_cb, gpointer user_data);
diff --git a/libpurple/util.h b/libpurple/util.h
--- a/libpurple/util.h
+++ b/libpurple/util.h
@@ -1056,7 +1056,18 @@ gboolean purple_validate(const PurplePlu
  */
 gboolean purple_str_has_prefix(const char *s, const char *p);
 
-gboolean purple_str_has_caseprefix(const gchar *s, const gchar *p);
+/**
+ * purple_str_has_caseprefix:
+ * @s: The string to check.
+ * @p: The prefix in question.
+ *
+ * Compares two strings to see if the first contains the second as
+ * a proper case-insensitive prefix.
+ *
+ * Returns: %TRUE if @p is a prefix of @s, otherwise %FALSE.
+ */
+gboolean
+purple_str_has_caseprefix(const gchar *s, const gchar *p);
 
 /**
  * purple_str_has_suffix:
diff --git a/pidgin/gtkutils.h b/pidgin/gtkutils.h
--- a/pidgin/gtkutils.h
+++ b/pidgin/gtkutils.h
@@ -944,6 +944,22 @@ GdkPixbuf *pidgin_pixbuf_new_from_file_a
  */
 GdkPixbuf *pidgin_pixbuf_new_from_file_at_scale(const char *filename, int width, int height, gboolean preserve_aspect_ratio);
 
+/**
+ * pidgin_pixbuf_scale_down:
+ * @src: The source image.
+ * @max_width: Maximum width in px.
+ * @max_height: Maximum height in px.
+ * @interp_type: Interpolation method.
+ * @preserve_ratio: %TRUE to preserve image's aspect ratio.
+ *
+ * Scales the image to the desired dimensions. If image is smaller, it will be
+ * returned without modifications.
+ *
+ * If new image is created, @src reference cound will be decreased and new image
+ * with a ref count of 1 will be returned.
+ *
+ * Returns: The image with proper sizing. %NULL in case of error.
+ */
 GdkPixbuf *
 pidgin_pixbuf_scale_down(GdkPixbuf *src, guint max_width, guint max_height,
 	GdkInterpType interp_type, gboolean preserve_ratio);
diff --git a/pidgin/gtkwebview.h b/pidgin/gtkwebview.h
--- a/pidgin/gtkwebview.h
+++ b/pidgin/gtkwebview.h
@@ -605,6 +605,13 @@ void pidgin_webview_hide_toolbar(PidginW
  */
 void pidgin_webview_activate_toolbar(PidginWebView *webview, PidginWebViewAction action);
 
+/**
+ * pidgin_webview_switch_active_conversation:
+ * @webview: The PidginWebView
+ * @conv: The conversation.
+ *
+ * Updates the webview for a new active #PurpleConversation.
+ */
 void
 pidgin_webview_switch_active_conversation(PidginWebView *webview,
 	PurpleConversation *conv);

