Mercurial > pidgin
changeset 25921:d25cbbea7fe5
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
| author | Mark Doliner <mark@kingant.net> |
|---|---|
| date | Mon, 26 Jan 2009 06:18:18 +0000 |
| parents | c0e3b62f8098 |
| children | 860d0c98d67d |
| 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 |
| diffstat | 10 files changed, 111 insertions(+), 38 deletions(-) [+] |
line wrap: on
line diff
--- a/libpurple/blist.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/blist.h Mon Jan 26 06:18:18 2009 +0000 @@ -75,6 +75,9 @@ } 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 @@ #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 @@ * 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 @@ * 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 @@ * 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 @@ * * @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 @@ * 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 @@ * * @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 @@ * @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 @@ * @param chat The chat. * * @constreturn The hashtable. + * * @since 2.4.0 */ GHashTable *purple_chat_get_components(PurpleChat *chat); @@ -1065,6 +1091,7 @@ * @param node The node. * * @return The type of the node. + * * @since 2.1.0 */ PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node);
--- a/libpurple/connection.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/connection.h Mon Jan 26 06:18:18 2009 +0000 @@ -42,7 +42,7 @@ 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 @@ } 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 @@ #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 @@ * * @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 @@ * @param gc The connection. * * @return The protocol plugin. + * * @since 2.4.0 */ PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc); @@ -422,6 +439,7 @@ * @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 @@ * @param gc the connection which is closing. * @param reason why the connection is closing. * @param description a non-@c NULL localized description of the error. + * * @since 2.3.0 */ void @@ -480,6 +499,7 @@ * 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 @@ * * @return @c TRUE if the account should not be automatically reconnected, and * @c FALSE otherwise. + * * @since 2.3.0 */ gboolean
--- a/libpurple/proxy.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/proxy.h Mon Jan 26 06:18:18 2009 +0000 @@ -190,6 +190,7 @@ * Set purple's global proxy information. * * @param info The proxy information. + * @since 2.6.0 */ void purple_global_proxy_set_info(PurpleProxyInfo *info);
--- a/libpurple/request.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/request.h Mon Jan 26 06:18:18 2009 +0000 @@ -531,6 +531,7 @@ * @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 @@ * @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 @@ * @param ui_data The UI data. * * @return The UI data. + * * @since 2.6.0 */ void purple_request_field_set_ui_data(PurpleRequestField *field,
--- a/libpurple/util.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/util.h Mon Jan 26 06:18:18 2009 +0000 @@ -784,6 +784,7 @@ * @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);
--- a/libpurple/xmlnode.h Mon Jan 26 06:03:06 2009 +0000 +++ b/libpurple/xmlnode.h Mon Jan 26 06:18:18 2009 +0000 @@ -309,6 +309,8 @@ * @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);
--- a/pidgin/gtkblist.h Mon Jan 26 06:03:06 2009 +0000 +++ b/pidgin/gtkblist.h Mon Jan 26 06:18:18 2009 +0000 @@ -255,13 +255,17 @@ * 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);
--- a/pidgin/gtkimhtml.h Mon Jan 26 06:03:06 2009 +0000 +++ b/pidgin/gtkimhtml.h Mon Jan 26 06:18:18 2009 +0000 @@ -60,6 +60,10 @@ 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 @@ * 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 @@ * @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 @@ * @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 @@ * @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);
--- a/pidgin/gtksound.h Mon Jan 26 06:03:06 2009 +0000 +++ b/pidgin/gtksound.h Mon Jan 26 06:18:18 2009 +0000 @@ -66,7 +66,9 @@ /** * 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);
--- a/pidgin/gtkutils.h Mon Jan 26 06:03:06 2009 +0000 +++ b/pidgin/gtkutils.h Mon Jan 26 06:18:18 2009 +0000 @@ -792,7 +792,8 @@ * * @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 @@ * @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);