/pidgin/main: 4a11e5ecb4ca: Smiley parser: fill docs

[Tomasz Wasilczyk]

Changeset: 4a11e5ecb4cae73e0fd37b9adc582bb04939f015
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-08 14:22 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/4a11e5ecb4ca

Description:

Smiley parser: fill docs

diffstat:

 libpurple/smiley-parser.h |  25 ++++++++++++++++++-------
 1 files changed, 18 insertions(+), 7 deletions(-)

diffs (48 lines):

diff --git a/libpurple/smiley-parser.h b/libpurple/smiley-parser.h
--- a/libpurple/smiley-parser.h
+++ b/libpurple/smiley-parser.h
@@ -64,12 +64,17 @@ typedef gboolean (*PurpleSmileyParseCb)(
  * @ui_data: the user data to be passed to @cb and
  *           #purple_smiley_theme_get_smileys.
  *
- * Replaces all textual smiley representations with proper smiley images.
+ * Replaces all textual smiley representations with proper smiley images
+ * configured for libpurple.
  *
  * The @use_remote_smileys parameter should be %TRUE for incoming messages,
  * %FALSE for outgoing.
  *
- * Returns: (transfer full): the smileyifed message. Should be #g_free'd when
+ * This function is intended for replacing all smileys before displaying. For
+ * replacing custom smileys before sending to the other party,
+ * see #purple_smiley_parser_replace.
+ *
+ * Returns: (transfer full): the smileifed message. Should be #g_free'd when
  *          done using it. Returns %NULL if and only if @html_message was %NULL.
  */
 gchar *
@@ -78,13 +83,19 @@ purple_smiley_parser_smileify(PurpleConv
 
 /**
  * purple_smiley_parser_replace:
- * @html_message:
- * @cb:
- * @ui_data:
+ * @smileys: the list of smileys to replace.
+ * @html_message: the html message, or escaped plain message.
+ * @cb: the callback to replace smiley text with an image.
+ * @ui_data: the user data to be passed to @cb.
  *
- * TODO
+ * Replaces all textual smiley representations from @smileys list with images.
  *
- * Returns: TODO
+ * This function is intended for replacing custom smileys before sending to the
+ * other party. For replacing all sets of smileys (custom, remote and theme) at
+ * once (ie. before displaying), use #purple_smiley_parser_smileify.
+ *
+ * Returns: (transfer full): the smileifed message. Should be #g_free'd when
+ *          done using it. Returns %NULL if and only if @html_message was %NULL.
  */
 gchar *
 purple_smiley_parser_replace(PurpleSmileyList *smileys,