/soc/2013/ankitkv/gobjectification: 49e48581843b: Convert doxyge...
Ankit Vani
a at nevitus.org
Wed Jan 29 16:25:54 EST 2014
Changeset: 49e48581843bea0471d218dde2fb6aea771a659c
Author: Ankit Vani <a at nevitus.org>
Date: 2014-01-30 02:45 +0530
Branch: soc.2013.gobjectification.gtkdoc
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/49e48581843b
Description:
Convert doxygen comments to gtk-doc format for circularbuffer, cmds, core
diffstat:
libpurple/circularbuffer.h | 53 ++++++++++-------
libpurple/cmds.h | 134 ++++++++++++++++++++++++++++----------------
libpurple/core.h | 37 +++++++++--
3 files changed, 146 insertions(+), 78 deletions(-)
diffs (truncated from 506 to 300 lines):
diff --git a/libpurple/circularbuffer.h b/libpurple/circularbuffer.h
--- a/libpurple/circularbuffer.h
+++ b/libpurple/circularbuffer.h
@@ -62,96 +62,105 @@ G_BEGIN_DECLS
GType purple_circular_buffer_get_type(void);
/**
- * Creates a new circular buffer. This will not allocate any memory for the
- * actual buffer until data is appended to it.
- *
+ * purple_circular_buffer_new:
* @growsize: The amount that the buffer should grow the first time data
* is appended and every time more space is needed. Pass in
* "0" to use the default of 256 bytes.
*
+ * Creates a new circular buffer. This will not allocate any memory for the
+ * actual buffer until data is appended to it.
+ *
* Returns: The new PurpleCircularBuffer.
*/
PurpleCircularBuffer *purple_circular_buffer_new(gsize growsize);
/**
- * Append data to the PurpleCircularBuffer. This will grow the internal
- * buffer to fit the added data, if needed.
- *
+ * purple_circular_buffer_append:
* @buf: The PurpleCircularBuffer to which to append the data
* @src: pointer to the data to copy into the buffer
* @len: number of bytes to copy into the buffer
+ *
+ * Append data to the PurpleCircularBuffer. This will grow the internal
+ * buffer to fit the added data, if needed.
*/
void purple_circular_buffer_append(PurpleCircularBuffer *buf, gconstpointer src, gsize len);
/**
+ * purple_circular_buffer_get_max_read:
+ * @buf: the PurpleCircularBuffer for which to determine the maximum
+ * contiguous bytes that can be read.
+ *
* Determine the maximum number of contiguous bytes that can be read from the
* PurpleCircularBuffer.
* Note: This may not be the total number of bytes that are buffered - a
* subsequent call after calling purple_circular_buffer_mark_read() may indicate
* more data is available to read.
*
- * @buf: the PurpleCircularBuffer for which to determine the maximum
- * contiguous bytes that can be read.
- *
* Returns: the number of bytes that can be read from the PurpleCircularBuffer
*/
gsize purple_circular_buffer_get_max_read(const PurpleCircularBuffer *buf);
/**
- * Mark the number of bytes that have been read from the buffer.
- *
+ * purple_circular_buffer_mark_read:
* @buf: The PurpleCircularBuffer to mark bytes read from
* @len: The number of bytes to mark as read
*
+ * Mark the number of bytes that have been read from the buffer.
+ *
* Returns: TRUE if we successfully marked the bytes as having been read, FALSE
* otherwise.
*/
gboolean purple_circular_buffer_mark_read(PurpleCircularBuffer *buf, gsize len);
/**
+ * purple_circular_buffer_grow:
+ * @buffer: The PurpleCircularBuffer to grow.
+ * @len: The number of bytes the buffer should be able to hold.
+ *
* Increases the buffer size by a multiple of grow size, so that it can hold at
* least 'len' bytes.
- *
- * @buffer: The PurpleCircularBuffer to grow.
- * @len: The number of bytes the buffer should be able to hold.
*/
void purple_circular_buffer_grow(PurpleCircularBuffer *buffer, gsize len);
/**
+ * purple_circular_buffer_get_grow_size:
+ * @buffer: The PurpleCircularBuffer from which to get grow size.
+ *
* Returns the number of bytes by which the buffer grows when more space is
* needed.
*
- * @buffer: The PurpleCircularBuffer from which to get grow size.
- *
* Returns: The grow size of the buffer.
*/
gsize purple_circular_buffer_get_grow_size(const PurpleCircularBuffer *buffer);
/**
+ * purple_circular_buffer_get_used:
+ * @buffer: The PurpleCircularBuffer from which to get used count.
+ *
* Returns the number of bytes of this buffer that contain unread data.
*
- * @buffer: The PurpleCircularBuffer from which to get used count.
- *
* Returns: The number of bytes that contain unread data.
*/
gsize purple_circular_buffer_get_used(const PurpleCircularBuffer *buffer);
/**
+ * purple_circular_buffer_get_output:
+ * @buffer: The PurpleCircularBuffer from which to get the output pointer.
+ *
* Returns the output pointer of the buffer, where unread data is available.
* Use purple_circular_buffer_get_max_read() to determine the number of
* contiguous bytes that can be read from this output. After reading the data,
* call purple_circular_buffer_mark_read() to mark the retrieved data as read.
*
- * @buffer: The PurpleCircularBuffer from which to get the output pointer.
- *
* Returns: The output pointer for the buffer.
*/
const gchar *purple_circular_buffer_get_output(const PurpleCircularBuffer *buffer);
/**
+ * purple_circular_buffer_reset:
+ * @buffer: The PurpleCircularBuffer to reset.
+ *
* Resets the buffer contents.
- *
- * @buffer: The PurpleCircularBuffer to reset.
*/
void purple_circular_buffer_reset(PurpleCircularBuffer *buffer);
diff --git a/libpurple/cmds.h b/libpurple/cmds.h
--- a/libpurple/cmds.h
+++ b/libpurple/cmds.h
@@ -31,7 +31,11 @@
/**************************************************************************/
/*@{*/
-/** The possible results of running a command with purple_cmd_do_command(). */
+/**
+ * PurpleCmdStatus:
+ *
+ * The possible results of running a command with purple_cmd_do_command().
+ */
typedef enum {
PURPLE_CMD_STATUS_OK,
PURPLE_CMD_STATUS_FAILED,
@@ -41,30 +45,44 @@ typedef enum {
PURPLE_CMD_STATUS_WRONG_TYPE
} PurpleCmdStatus;
-/** Commands registered with the core return one of these values when run.
- * Normally, a command will want to return one of the first two; in some
- * unusual cases, you might want to have several functions called for a
- * particular command; in this case, they should return
- * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
- * commands with the same name.
+/**
+ * PurpleCmdRet:
+ * @PURPLE_CMD_RET_OK: Everything's okay; Don't look for another command
+ * to call.
+ * @PURPLE_CMD_RET_FAILED: The command failed, but stop looking.
+ * @PURPLE_CMD_RET_CONTINUE: Continue, looking for other commands with the same
+ * name to call.
+ *
+ * Commands registered with the core return one of these values when run.
+ * Normally, a command will want to return one of the first two; in some
+ * unusual cases, you might want to have several functions called for a
+ * particular command; in this case, they should return
+ * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
+ * commands with the same name.
*/
typedef enum {
- PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */
- PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/
- PURPLE_CMD_RET_CONTINUE /**< Continue, looking for other commands with the same name to call. */
+ PURPLE_CMD_RET_OK,
+ PURPLE_CMD_RET_FAILED,
+ PURPLE_CMD_RET_CONTINUE
} PurpleCmdRet;
#define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
-/** A function implementing a command, as passed to purple_cmd_register().
+/**
+ * PurpleCmdFunc:
*
- * @todo document the arguments to these functions.
- * */
+ * A function implementing a command, as passed to purple_cmd_register().
+ *
+ * @todo document the arguments to these functions.
+ */
typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
gchar **args, gchar **error, void *data);
-/** A unique integer representing a command registered with
- * purple_cmd_register(), which can subsequently be passed to
- * purple_cmd_unregister() to unregister that command.
+/**
+ * PurpleCmdId:
+ *
+ * A unique integer representing a command registered with
+ * purple_cmd_register(), which can subsequently be passed to
+ * purple_cmd_unregister() to unregister that command.
*/
typedef guint PurpleCmdId;
@@ -79,20 +97,25 @@ typedef enum {
PURPLE_CMD_P_VERY_HIGH = 6000
} PurpleCmdPriority;
-/** Flags used to set various properties of commands. Every command should
- * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
- * order to be even slighly useful.
+/**
+ * PurpleCmdFlag:
+ * @PURPLE_CMD_FLAG_IM: Command is usable in IMs.
+ * @PURPLE_CMD_FLAG_CHAT: Command is usable in multi-user chats.
+ * @PURPLE_CMD_FLAG_PROTOCOL_ONLY: Command is usable only for a particular
+ * protocol.
+ * @PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS: Incorrect arguments to this command
+ * should be accepted anyway.
*
- * @see purple_cmd_register
+ * Flags used to set various properties of commands. Every command should
+ * have at least one of #PURPLE_CMD_FLAG_IM and #PURPLE_CMD_FLAG_CHAT set in
+ * order to be even slighly useful.
+ *
+ * @see purple_cmd_register
*/
typedef enum {
- /** Command is usable in IMs. */
PURPLE_CMD_FLAG_IM = 0x01,
- /** Command is usable in multi-user chats. */
PURPLE_CMD_FLAG_CHAT = 0x02,
- /** Command is usable only for a particular protocol. */
- PURPLE_CMD_FLAG_PROTOCOL_ONLY = 0x04,
- /** Incorrect arguments to this command should be accepted anyway. */
+ PURPLE_CMD_FLAG_PROTOCOL_ONLY = 0x04,
PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS = 0x08
} PurpleCmdFlag;
@@ -107,17 +130,13 @@ G_BEGIN_DECLS
/*@{*/
/**
- * Register a new command with the core.
- *
- * The command will only happen if commands are enabled,
- * which is a UI pref. UIs don't have to support commands at all.
- *
+ * purple_cmd_register:
* @cmd: The command. This should be a UTF-8 (or ASCII) string, with no spaces
* or other white space.
* @args: A string of characters describing to libpurple how to parse this
* command's arguments. If what the user types doesn't match this
* pattern, libpurple will keep looking for another command, unless
- * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f.
+ * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @f.
* This string should contain no whitespace, and use a single
* character for each argument. The recognized characters are:
* <ul>
@@ -128,7 +147,7 @@ G_BEGIN_DECLS
* <li><tt>'S'</tt>: Same as <tt>'s'</tt> but with formatting.</li>
* </ul>
* If args is the empty string, then the command accepts no arguments.
- * The args passed to the callback @a func will be a %NULL
+ * The args passed to the callback @func will be a %NULL
* terminated array of %NULL terminated strings, and will always
* match the number of arguments asked for, unless
* #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
@@ -152,30 +171,33 @@ G_BEGIN_DECLS
* followed by a colon, two spaces, and a description of the
* command in sentence form. Do not include a slash before the
* command name.
- * @data: User defined data to pass to the #PurpleCmdFunc @a f.
+ * @data: User defined data to pass to the #PurpleCmdFunc @f.
+ *
+ * Register a new command with the core.
+ *
+ * The command will only happen if commands are enabled,
+ * which is a UI pref. UIs don't have to support commands at all.
+ *
* Returns: A #PurpleCmdId, which is only used for calling
- * #purple_cmd_unregister, or @a 0 on failure.
+ * #purple_cmd_unregister, or 0 on failure.
*/
PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f,
const gchar *protocol_id, PurpleCmdFunc func, const gchar *helpstr, void *data);
/**
+ * purple_cmd_unregister:
+ * @id: The #PurpleCmdId to unregister, as returned by #purple_cmd_register.
+ *
* Unregister a command with the core.
*
* All registered commands must be unregistered, if they're registered by a plugin
* or something else that might go away. Normally this is called when the plugin
* unloads itself.
- *
More information about the Commits
mailing list