/pidgin/main: e1f9a50effbc: Fill comments for PurpleMessage

Changeset: e1f9a50effbcaf9211d9305f320f00b65a7461c6
Author:	 Tomasz Wasilczyk <[email protected]>
Date:	 2014-06-14 00:28 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/e1f9a50effbc

Description:

Fill comments for PurpleMessage

diffstat:

 doc/reference/libpurple/libpurple-docs.xml |   18 ++-
 libpurple/internal.h                       |   16 +++
 libpurple/message.c                        |    2 +-
 libpurple/message.h                        |  147 +++++++++++++++++++++++++++-
 4 files changed, 169 insertions(+), 14 deletions(-)

diffs (truncated from 322 to 300 lines):

diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -38,7 +38,6 @@
       <xi:include href="xml/pounce.xml" />
       <xi:include href="xml/circularbuffer.xml" />
       <xi:include href="xml/cipher.xml" />
-      <xi:include href="xml/cmds.xml" />
       <xi:include href="xml/connection.xml" />
       <xi:include href="xml/conversation.xml" />
       <xi:include href="xml/conversationtypes.xml" />
@@ -54,7 +53,6 @@
       <xi:include href="xml/http.xml" />
       <xi:include href="xml/idle.xml" />
       <xi:include href="xml/keyring.xml" />
-      <xi:include href="xml/log.xml" />
       <xi:include href="xml/memorypool.xml" />
       <xi:include href="xml/desktopitem.xml" />
       <xi:include href="xml/mime.xml" />
@@ -97,6 +95,14 @@
 
   <reference label="">
     <reference label="a">
+      <title>Messaging</title>
+
+        <xi:include href="xml/message.xml" />
+        <xi:include href="xml/log.xml" />
+        <xi:include href="xml/cmds.xml" />
+    </reference>
+
+    <reference label="b">
       <title>Ciphers and Hashes</title>
 
         <xi:include href="xml/aescipher.xml" />
@@ -111,7 +117,7 @@
         <xi:include href="xml/sha256hash.xml" />
     </reference>
 
-    <reference label="b">
+    <reference label="c">
       <title>Smiley APIs</title>
 
         <xi:include href="xml/smiley.xml" />
@@ -121,7 +127,7 @@
         <xi:include href="xml/smiley-parser.xml" />
     </reference>
 
-    <reference label="c">
+    <reference label="d">
       <title>Graphics</title>
 
         <xi:include href="xml/image.xml" />
@@ -129,7 +135,7 @@
         <xi:include href="xml/whiteboard.xml" />
     </reference>
 
-    <reference label="d">
+    <reference label="e">
       <title>Media APIs</title>
 
         <xi:include href="xml/media.xml" />
@@ -141,7 +147,7 @@
         <xi:include href="xml/enum-types.xml" />
     </reference>
 
-    <reference label="e">
+    <reference label="f">
       <title>D-Bus Server APIs</title>
 
         <xi:include href="xml/dbus-bindings.xml" />
diff --git a/libpurple/internal.h b/libpurple/internal.h
--- a/libpurple/internal.h
+++ b/libpurple/internal.h
@@ -395,6 +395,22 @@ void
 void
 _purple_socket_uninit(void);
 
+/**
+ * _purple_message_init: (skip)
+ *
+ * Initializes the #PurpleMessage subsystem.
+ */
+void
+_purple_message_init(void);
+
+/**
+ * _purple_message_uninit: (skip)
+ *
+ * Uninitializes the #PurpleMessage subsystem.
+ */
+void
+_purple_message_uninit(void);
+
 void
 _purple_assert_connection_is_valid(PurpleConnection *gc,
 	const gchar *file, int line);
diff --git a/libpurple/message.c b/libpurple/message.c
--- a/libpurple/message.c
+++ b/libpurple/message.c
@@ -362,7 +362,7 @@ purple_message_class_init(PurpleMessageC
 		"Contents", "The message text",
 		NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 	properties[PROP_TIME] = g_param_spec_uint64("time",
-		"Time", "Message time",
+		"Time", "Message timestamp",
 		0, G_MAXUINT64, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 	properties[PROP_FLAGS] = g_param_spec_flags("flags",
 		"Flags", "Bitwise set of #PurpleMessageFlags flags",
diff --git a/libpurple/message.h b/libpurple/message.h
--- a/libpurple/message.h
+++ b/libpurple/message.h
@@ -48,7 +48,7 @@ typedef struct _PurpleMessageClass Purpl
 /**
  * PurpleMessage:
  *
- * An message data container.
+ * A message data container.
  */
 struct _PurpleMessage
 {
@@ -82,62 +82,195 @@ G_BEGIN_DECLS
 GType
 purple_message_get_type(void);
 
+/**
+ * purple_message_new_outgoing:
+ * @who: Message's recipient.
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ *
+ * Creates new outgoing message (the user is the author).
+ *
+ * You don't need to set the #PURPLE_MESSAGE_SEND flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
 PurpleMessage *
 purple_message_new_outgoing(const gchar *who, const gchar *contents,
 	PurpleMessageFlags flags);
 
+/**
+ * purple_message_new_incoming:
+ * @who: Message's author.
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ * @timestamp: The time of transmitting a message. May be %0 for a current time.
+ *
+ * Creates new incoming message (the user is the recipient).
+ *
+ * You don't need to set the #PURPLE_MESSAGE_RECV flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
 PurpleMessage *
 purple_message_new_incoming(const gchar *who, const gchar *contents,
 	PurpleMessageFlags flags, guint64 timestamp);
 
+/**
+ * purple_message_new_system:
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ *
+ * Creates new system message.
+ *
+ * You don't need to set the #PURPLE_MESSAGE_SYSTEM flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
 PurpleMessage *
 purple_message_new_system(const gchar *contents, PurpleMessageFlags flags);
 
+/**
+ * purple_message_get_id:
+ * @msg: The message.
+ *
+ * Returns the unique identifier of the message. These identifiers are not
+ * serialized - it's a per-session id.
+ *
+ * Returns: the global identifier of @msg.
+ */
 guint
 purple_message_get_id(const PurpleMessage *msg);
 
+/**
+ * purple_message_find_by_id:
+ * @id: The message identifier.
+ *
+ * Finds the message with a given @id.
+ *
+ * Returns: the #PurpleMessage, or %NULL if not found.
+ */
 PurpleMessage *
 purple_message_find_by_id(guint id);
 
+/**
+ * purple_message_get_author:
+ * @msg: The message.
+ *
+ * Returns the author of the message - his screen name (not a local alias).
+ *
+ * Returns: the author of @msg.
+ */
 const gchar *
 purple_message_get_author(const PurpleMessage *msg);
 
+/**
+ * purple_message_get_recipient:
+ * @msg: The message.
+ *
+ * Returns the recipient of the message - his screen name (not a local alias).
+ *
+ * Returns: the recipient of @msg.
+ */
 const gchar *
 purple_message_get_recipient(const PurpleMessage *msg);
 
+/**
+ * purple_message_set_author_alias:
+ * @msg: The message.
+ * @alias: The alias.
+ *
+ * Sets the alias of @msg's author. You don't normally need to call this.
+ */
 void
 purple_message_set_author_alias(PurpleMessage *msg, const gchar *alias);
 
+/**
+ * purple_message_get_author_alias:
+ * @msg: The message.
+ *
+ * Returns the alias of @msg author.
+ *
+ * Returns: the @msg author's alias.
+ */
 const gchar *
 purple_message_get_author_alias(const PurpleMessage *msg);
 
+/**
+ * purple_message_set_contents:
+ * @msg: The message.
+ * @cont: The contents.
+ *
+ * Sets the contents of the @msg. It might be HTML.
+ */
 void
 purple_message_set_contents(PurpleMessage *msg, const gchar *cont);
 
+/**
+ * purple_message_get_contents:
+ * @msg: The message.
+ *
+ * Returns the contents of the message.
+ *
+ * Returns: the contents of @msg.
+ */
 const gchar *
 purple_message_get_contents(const PurpleMessage *msg);
 
+/**
+ * purple_message_is_empty:
+ * @msg: The message.
+ *
+ * Checks, if the message's body is empty.
+ *
+ * Returns: %TRUE, if @msg is empty.
+ */
 gboolean
 purple_message_is_empty(const PurpleMessage *msg);
 
+/**
+ * purple_message_set_time:
+ * @msg: The message.
+ * @msgtime: The timestamp of a message.
+ *
+ * Sets the @msg's timestamp. It should be a date of posting, but it can be
+ * a date of receiving (if the former is not available).
+ */
 void
 purple_message_set_time(PurpleMessage *msg, guint64 msgtime);
 
+/**
+ * purple_message_get_time:
+ * @msg: The message.
+ *
+ * Returns a @msg's timestamp.
+ *
+ * Returns: @msg's timestamp.
+ */
 guint64
 purple_message_get_time(const PurpleMessage *msg);
 
+/**
+ * purple_message_set_flags:
+ * @msg: The message.
+ * @flags: The message flags.
+ *
+ * Sets flags for @msg. It shouldn't be in a conflict with a message type,
+ * so use it carefully.
+ */
 void