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);