pidgin.next.minor: 6195ce79: Add @since 2.6.0 doxygen comments to som...
markdoliner at pidgin.im
markdoliner at pidgin.im
Mon Jan 26 01:25:27 EST 2009
-----------------------------------------------------------------
Revision: 6195ce7967cb0651ad4582ba1d5ade7c47a3ba87
Ancestor: c5cd4dbdd6ea49cc2d0ca7bbf54c87de0f5dc13a
Author: markdoliner at pidgin.im
Date: 2009-01-26T06:18:18
Branch: im.pidgin.pidgin.next.minor
URL: http://d.pidgin.im/viewmtn/revision/info/6195ce7967cb0651ad4582ba1d5ade7c47a3ba87
Modified files:
libpurple/blist.h libpurple/connection.h libpurple/proxy.h
libpurple/request.h libpurple/util.h libpurple/xmlnode.h
pidgin/gtkblist.h pidgin/gtkimhtml.h pidgin/gtksound.h
pidgin/gtkutils.h
ChangeLog:
Add @since 2.6.0 doxygen comments to some of our new functions, and
try to make the formatting of our comments a little more uniform
-------------- next part --------------
============================================================
--- libpurple/blist.h 8fa3e4b3aa1f43a094becf2f2a000e0d0af43361
+++ libpurple/blist.h c289823582d1acdf4c3cce1fd2534488ccbc9321
@@ -75,6 +75,9 @@ typedef enum
} PurpleBlistNodeFlags;
+/**
+ * @since 2.6.0
+ */
#define PURPLE_BLIST_NODE(obj) ((PurpleBlistNode *)(obj))
#define PURPLE_BLIST_NODE_HAS_FLAG(b, f) (purple_blist_node_get_flags((PurpleBlistNode*)(b)) & (f))
@@ -83,9 +86,24 @@ typedef enum
#define PURPLE_BLIST_NODE_NAME(n) (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE ? purple_chat_get_name((PurpleChat*)n) : \
purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE ? purple_buddy_get_name((PurpleBuddy*)n) : NULL)
+/**
+ * @since 2.6.0
+ */
#define PURPLE_GROUP(obj) ((PurpleGroup *)(obj))
+
+/**
+ * @since 2.6.0
+ */
#define PURPLE_CONTACT(obj) ((PurpleContact *)(obj))
+
+/**
+ * @since 2.6.0
+ */
#define PURPLE_BUDDY(obj) ((PurpleBuddy *)(obj))
+
+/**
+ * @since 2.6.0
+ */
#define PURPLE_CHAT(obj) ((PurpleChat *)(obj))
#include "account.h"
@@ -245,6 +263,7 @@ PurpleBlistNode *purple_blist_get_root(v
* Returns the hash table of every buddy in the list.
*
* @return The hash table of every buddy in the list.
+ *
* @since 2.6.0
*/
GHashTable *purple_blist_get_buddies(void);
@@ -253,6 +272,7 @@ GHashTable *purple_blist_get_buddies(voi
* Returns the UI data for the list.
*
* @return The UI data for the list.
+ *
* @since 2.6.0
*/
void *purple_blist_get_ui_data(void);
@@ -261,6 +281,7 @@ void *purple_blist_get_ui_data(void);
* Sets the UI data for the list.
*
* @param ui_data The UI data for the list.
+ *
* @since 2.6.0
*/
void purple_blist_set_ui_data(void *ui_data);
@@ -345,6 +366,7 @@ void *purple_blist_node_get_ui_data(cons
*
* @param node The node.
* @param ui_data The UI data.
+ *
* @since 2.6.0
*/
void purple_blist_node_set_ui_data(PurpleBlistNode *node, void *ui_data);
@@ -379,6 +401,7 @@ void purple_blist_update_buddy_status(Pu
* Updates a node's custom icon.
*
* @param node The PurpleBlistNode whose custom icon has changed.
+ *
* @since 2.5.0
*/
void purple_blist_update_node_icon(PurpleBlistNode *node);
@@ -761,6 +784,7 @@ const char *purple_buddy_get_alias(Purpl
*
* @param buddy The buddy
* @return The local alias for the buddy
+ *
* @since 2.6.0
*/
const char *purple_buddy_get_local_buddy_alias(PurpleBuddy *buddy);
@@ -837,6 +861,7 @@ PurpleGroup *purple_chat_get_group(Purpl
* @param chat The chat.
*
* @return The account the chat belongs to.
+ *
* @since 2.4.0
*/
PurpleAccount *purple_chat_get_account(PurpleChat *chat);
@@ -847,6 +872,7 @@ PurpleAccount *purple_chat_get_account(P
* @param chat The chat.
*
* @constreturn The hashtable.
+ *
* @since 2.4.0
*/
GHashTable *purple_chat_get_components(PurpleChat *chat);
@@ -1065,6 +1091,7 @@ PurpleBlistNodeFlags purple_blist_node_g
* @param node The node.
*
* @return The type of the node.
+ *
* @since 2.1.0
*/
PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node);
============================================================
--- libpurple/connection.h 1bd3920357894ffee057afb36597b71b53ecca0f
+++ libpurple/connection.h 9dd15afce16ecc438832fd2aa5cd9885538850ab
@@ -42,7 +42,7 @@ typedef enum
PURPLE_CONNECTION_FORMATTING_WBFO = 0x0008, /**< The text buffer must be formatted as a whole */
PURPLE_CONNECTION_NO_NEWLINES = 0x0010, /**< No new lines are allowed in outgoing messages */
PURPLE_CONNECTION_NO_FONTSIZE = 0x0020, /**< Connection does not send/receive font sizes */
- PURPLE_CONNECTION_NO_URLDESC = 0x0040, /**< Connection does not support descriptions with links */
+ PURPLE_CONNECTION_NO_URLDESC = 0x0040, /**< Connection does not support descriptions with links */
PURPLE_CONNECTION_NO_IMAGES = 0x0080, /**< Connection does not support sending of images */
PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY = 0x0100 /**< Connection supports sending and receiving custom smileys */
@@ -56,7 +56,9 @@ typedef enum
} PurpleConnectionState;
-/** Possible errors that can cause a connection to be closed.
+/**
+ * Possible errors that can cause a connection to be closed.
+ *
* @since 2.3.0
*/
typedef enum
@@ -148,71 +150,84 @@ typedef struct
#include "status.h"
#include "sslconn.h"
-/** Connection UI operations. Used to notify the user of changes to
- * connections, such as being disconnected, and to respond to the
- * underlying network connection appearing and disappearing. UIs should
- * call #purple_connections_set_ui_ops() with an instance of this struct.
+/**
+ * Connection UI operations. Used to notify the user of changes to
+ * connections, such as being disconnected, and to respond to the
+ * underlying network connection appearing and disappearing. UIs should
+ * call #purple_connections_set_ui_ops() with an instance of this struct.
*
- * @see @ref ui-ops
+ * @see @ref ui-ops
*/
typedef struct
{
- /** When an account is connecting, this operation is called to notify
- * the UI of what is happening, as well as which @a step out of @a
- * step_count has been reached (which might be displayed as a progress
- * bar).
- * @see #purple_connection_update_progress
+ /**
+ * When an account is connecting, this operation is called to notify
+ * the UI of what is happening, as well as which @a step out of @a
+ * step_count has been reached (which might be displayed as a progress
+ * bar).
+ * @see #purple_connection_update_progress
*/
void (*connect_progress)(PurpleConnection *gc,
const char *text,
size_t step,
size_t step_count);
- /** Called when a connection is established (just before the
- * @ref signed-on signal).
+ /**
+ * Called when a connection is established (just before the
+ * @ref signed-on signal).
*/
void (*connected)(PurpleConnection *gc);
- /** Called when a connection is ended (between the @ref signing-off
- * and @ref signed-off signals).
+
+ /**
+ * Called when a connection is ended (between the @ref signing-off
+ * and @ref signed-off signals).
*/
void (*disconnected)(PurpleConnection *gc);
- /** Used to display connection-specific notices. (Pidgin's Gtk user
- * interface implements this as a no-op; #purple_connection_notice(),
- * which uses this operation, is not used by any of the protocols
- * shipped with libpurple.)
+ /**
+ * Used to display connection-specific notices. (Pidgin's Gtk user
+ * interface implements this as a no-op; #purple_connection_notice(),
+ * which uses this operation, is not used by any of the protocols
+ * shipped with libpurple.)
*/
void (*notice)(PurpleConnection *gc, const char *text);
- /** Called when an error causes a connection to be disconnected.
- * Called before #disconnected.
- * @param text a localized error message.
- * @see #purple_connection_error
- * @deprecated in favour of
- * #PurpleConnectionUiOps.report_disconnect_reason.
+ /**
+ * Called when an error causes a connection to be disconnected.
+ * Called before #disconnected.
+ * @param text a localized error message.
+ * @see #purple_connection_error
+ * @deprecated in favour of
+ * #PurpleConnectionUiOps.report_disconnect_reason.
*/
void (*report_disconnect)(PurpleConnection *gc, const char *text);
- /** Called when libpurple discovers that the computer's network
- * connection is active. On Linux, this uses Network Manager if
- * available; on Windows, it uses Win32's network change notification
- * infrastructure.
+ /**
+ * Called when libpurple discovers that the computer's network
+ * connection is active. On Linux, this uses Network Manager if
+ * available; on Windows, it uses Win32's network change notification
+ * infrastructure.
*/
void (*network_connected)(void);
- /** Called when libpurple discovers that the computer's network
- * connection has gone away.
+
+ /**
+ * Called when libpurple discovers that the computer's network
+ * connection has gone away.
*/
void (*network_disconnected)(void);
- /** Called when an error causes a connection to be disconnected.
+ /**
+ * Called when an error causes a connection to be disconnected.
* Called before #disconnected. This op is intended to replace
* #report_disconnect. If both are implemented, this will be called
* first; however, there's no real reason to implement both.
+ *
* @param reason why the connection ended, if known, or
* #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not.
* @param text a localized message describing the disconnection
* in more detail to the user.
* @see #purple_connection_error_reason
+ *
* @since 2.3.0
*/
void (*report_disconnect_reason)(PurpleConnection *gc,
@@ -358,6 +373,7 @@ void purple_connection_set_display_name(
*
* @param connection The PurpleConnection.
* @param proto_data The protocol data to set for the connection.
+ *
* @since 2.6.0
*/
void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data);
@@ -394,6 +410,7 @@ PurpleAccount *purple_connection_get_acc
* @param gc The connection.
*
* @return The protocol plugin.
+ *
* @since 2.4.0
*/
PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc);
@@ -422,6 +439,7 @@ const char *purple_connection_get_displa
* @param connection The PurpleConnection.
*
* @return The protocol data for the connection.
+ *
* @since 2.6.0
*/
void *purple_connection_get_protocol_data(const PurpleConnection *connection);
@@ -469,6 +487,7 @@ void purple_connection_error(PurpleConne
* @param gc the connection which is closing.
* @param reason why the connection is closing.
* @param description a non- at c NULL localized description of the error.
+ *
* @since 2.3.0
*/
void
@@ -480,6 +499,7 @@ purple_connection_error_reason (PurpleCo
* Closes a connection due to an SSL error; this is basically a shortcut to
* turning the #PurpleSslErrorType into a #PurpleConnectionError and a
* human-readable string and then calling purple_connection_error_reason().
+ *
* @since 2.3.0
*/
void
@@ -503,6 +523,7 @@ purple_connection_ssl_error (PurpleConne
*
* @return @c TRUE if the account should not be automatically reconnected, and
* @c FALSE otherwise.
+ *
* @since 2.3.0
*/
gboolean
============================================================
--- libpurple/proxy.h 177eb80534fd4c1853983b712b192702f2279dc3
+++ libpurple/proxy.h dedab01a064de80b7c38d46c8625a9b25da78cd9
@@ -190,6 +190,7 @@ PurpleProxyInfo *purple_global_proxy_get
* Set purple's global proxy information.
*
* @param info The proxy information.
+ * @since 2.6.0
*/
void purple_global_proxy_set_info(PurpleProxyInfo *info);
============================================================
--- libpurple/request.h 67473fde8f962eccb12874d50fe747e304fbcbb8
+++ libpurple/request.h 14807424c3e87488f11544f36ae068dbd7437f20
@@ -531,6 +531,7 @@ PurpleRequestFieldType purple_request_fi
* @param field The field.
*
* @return The UI data.
+ *
* @since 2.6.0
*/
PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);
@@ -586,6 +587,7 @@ gboolean purple_request_field_is_require
* @param field The field.
*
* @return The UI data.
+ *
* @since 2.6.0
*/
gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);
@@ -597,6 +599,7 @@ gpointer purple_request_field_get_ui_dat
* @param ui_data The UI data.
*
* @return The UI data.
+ *
* @since 2.6.0
*/
void purple_request_field_set_ui_data(PurpleRequestField *field,
============================================================
--- libpurple/util.h d75c0030d8e1fceb03f825eb4ac41da30795423d
+++ libpurple/util.h 33fcf89b496433e18db386d72628bd14b100c89b
@@ -784,6 +784,7 @@ char *purple_fd_get_ip(int fd);
* @param right A string to compare with left
*
* @return @c TRUE if the strings are the same, else @c FALSE.
+ *
* @since 2.6.0
*/
gboolean purple_strequal(const gchar *left, const gchar *right);
============================================================
--- libpurple/xmlnode.h 5278c3c3c551a6645c6b3234f760f39ff812c3ac
+++ libpurple/xmlnode.h e8f9beb0476e8b564d323f614a95183424fa3548
@@ -309,6 +309,8 @@ void xmlnode_free(xmlnode *node);
* @process The utility that is calling xmlnode_from_file
*
* @return The new node.
+ *
+ * @since 2.6.0
*/
xmlnode *xmlnode_from_file(const char *dir, const char *filename,
const char *description, const char *process);
============================================================
--- pidgin/gtkblist.h 6a35d2e32672c580550e3c1d746599057e0d7bc1
+++ pidgin/gtkblist.h 21bd550747b7adb901cb8e294272f433bbb36344
@@ -255,13 +255,17 @@ void pidgin_blist_add_alert(GtkWidget *w
* Sets the current theme for Pidgin to use
*
* @param theme the new theme to use
+ *
+ * @since 2.6.0
*/
void pidgin_blist_set_theme(PidginBlistTheme *theme);
/**
* Gets Pidgin's current buddy list theme
*
- * @returns the current theme
+ * @returns the current theme
+ *
+ * @since 2.6.0
*/
PidginBlistTheme *pidgin_blist_get_theme(void);
============================================================
--- pidgin/gtkimhtml.h d684251b6a734966c1304959aec53134cab55408
+++ pidgin/gtkimhtml.h b1c57b37d54fbf29e51f0c3bc3131f05f9c49b02
@@ -60,6 +60,10 @@ typedef struct _GtkIMHtmlFuncs GtkIMHtm
typedef struct _GtkIMHtmlAnimation GtkIMHtmlAnimation;
typedef struct _GtkIMHtmlHr GtkIMHtmlHr;
typedef struct _GtkIMHtmlFuncs GtkIMHtmlFuncs;
+
+/**
+ * @since 2.6.0
+ */
typedef struct _GtkIMHtmlLink GtkIMHtmlLink;
typedef enum {
@@ -903,6 +907,7 @@ void gtk_imhtml_smiley_destroy(GtkIMHtml
* successfully, @c FALSE otherwise.
*
* @return @c TRUE if the protocol was successfully registered (or unregistered, when #activate is @c NULL)
+ *
* @since 2.6.0
*/
gboolean gtk_imhtml_class_register_protocol(const char *name,
@@ -915,6 +920,7 @@ gboolean gtk_imhtml_class_register_proto
* @param link The GtkIMHtmlLink object sent to the callback functions
*
* @return The URL
+ *
* @since 2.6.0
*/
const char *gtk_imhtml_link_get_url(GtkIMHtmlLink *link);
@@ -925,9 +931,10 @@ const char *gtk_imhtml_link_get_url(GtkI
* @param link The GtkIMHtmlLink object sent to the callback functions
*
* @return The GtkTextTag object, or @c NULL
+ *
* @since 2.6.0
*/
-const GtkTextTag * gtk_imhtml_link_get_text_tag(GtkIMHtmlLink *link);
+const GtkTextTag *gtk_imhtml_link_get_text_tag(GtkIMHtmlLink *link);
/**
* Activates a GtkIMHtmlLink object. This triggers the 'url-clicked' signal, marks the
@@ -936,6 +943,7 @@ const GtkTextTag * gtk_imhtml_link_get_t
* @param link The GtkIMHtmlLink object sent to the callback functions
*
* @return @c TRUE if 'url-clicked' signal was emitted, @c FALSE otherwise.
+ *
* @since 2.6.0
*/
gboolean gtk_imhtml_link_activate(GtkIMHtmlLink *link);
============================================================
--- pidgin/gtksound.h 064f1e4731b6e1a5f71952a67710ed0892d93915
+++ pidgin/gtksound.h 132519f653121f18564d7dea38ef78c7f21a800a
@@ -66,7 +66,9 @@ void *pidgin_sound_get_handle(void);
/**
* Returns true Pidgin is using customized sounds
*
- * @return TRUE if non default sounds are used
+ * @return TRUE if non default sounds are used.
+ *
+ * @since 2.6.0
*/
gboolean pidgin_sound_is_customized(void);
============================================================
--- pidgin/gtkutils.h aaf8f8709bb13907d529a5cc6c1847c23d3b442b
+++ pidgin/gtkutils.h c0990a217a390c385d9bbd8fde11fcebf7b292ed
@@ -792,7 +792,8 @@ void pidgin_text_combo_box_entry_set_tex
*
* @param window The window to make transient.
*
- * @return Whether the window was made transient or not.
+ * @return Whether the window was made transient or not.
+ *
* @since 2.4.0
*/
gboolean pidgin_auto_parent_window(GtkWidget *window);
@@ -818,18 +819,21 @@ GtkWidget *pidgin_add_widget_to_vbox(Gtk
* @param image A PurpleStoredImage.
*
* @return A GdkPixbuf created from the stored image.
+ *
* @since 2.5.0
*/
-GdkPixbuf * pidgin_pixbuf_from_imgstore(PurpleStoredImage *image);
+GdkPixbuf *pidgin_pixbuf_from_imgstore(PurpleStoredImage *image);
/**
* Initialize some utility functions.
+ *
* @since 2.6.0
*/
void pidgin_utils_init(void);
/**
* Uninitialize some utility functions.
+ *
* @since 2.6.0
*/
void pidgin_utils_uninit(void);
More information about the Commits
mailing list