diff libpurple/notify.h @ 24415:d038fc351194

Remove stray whitespace and wrap the function comments at less than 80 characters.

--- a/libpurple/notify.h	Mon Nov 17 19:30:27 2008 +0000
+++ b/libpurple/notify.h	Mon Nov 17 21:31:36 2008 +0000
@@ -236,7 +236,8 @@
  * Adds a stock button that will be displayed in the search results dialog.
  *
  * @param results The search results object.
- * @param type    Type of the button. (TODO: Only one button of a given type can be displayed.)
+ * @param type    Type of the button. (TODO: Only one button of a given type
+ *                can be displayed.)
  * @param cb      Function that will be called on the click event.
  */
 void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results,
@@ -245,8 +246,9 @@
 
 
 /**
- * Adds a plain labelled button that will be displayed in the search results dialog.
- * 
+ * Adds a plain labelled button that will be displayed in the search results
+ * dialog.
+ *
  * @param results The search results object
  * @param label   The label to display
  * @param cb      Function that will be called on the click event
@@ -267,7 +269,7 @@
  * Returns a newly created search result column object.
  *
  * @param title Title of the column. NOTE: Title will get g_strdup()ed.
- * 
+ *
  * @return The new search column object.
  */
 PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title);
@@ -470,53 +472,58 @@
  * The text is essentially a stripped-down format of HTML, the same that
  * IMs may send.
  *
- * @param gc		         The PurpleConnection handle associated with the information.
- * @param who				 The username associated with the information.
- * @param user_info          The PurpleNotifyUserInfo which contains the information
- * @param cb                 The callback to call when the user closes
- *                           the notification.
- * @param user_data          The data to pass to the callback.
+ * @param gc         The PurpleConnection handle associated with the information.
+ * @param who        The username associated with the information.
+ * @param user_info  The PurpleNotifyUserInfo which contains the information
+ * @param cb         The callback to call when the user closes the notification.
+ * @param user_data  The data to pass to the callback.
  *
- * @return A UI-specific handle.
+ * @return  A UI-specific handle.
  */
 void *purple_notify_userinfo(PurpleConnection *gc, const char *who,
 						   PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb,
 						   gpointer user_data);
 
 /**
- * Create a new PurpleNotifyUserInfo which is suitable for passing to purple_notify_userinfo()
+ * Create a new PurpleNotifyUserInfo which is suitable for passing to
+ * purple_notify_userinfo()
  *
- * @return A new PurpleNotifyUserInfo, which the caller must destroy when done
+ * @return  A new PurpleNotifyUserInfo, which the caller must destroy when done
  */
 PurpleNotifyUserInfo *purple_notify_user_info_new(void);
 
 /**
  * Destroy a PurpleNotifyUserInfo
  *
- * @param user_info          The PurpleNotifyUserInfo
+ * @param user_info  The PurpleNotifyUserInfo
  */
 void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
 
 /**
- * Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo
- *
- * This GList may be manipulated directly with normal GList functions such as g_list_insert(). Only 
- * PurpleNotifyUserInfoEntry are allowed in the list.  If a PurpleNotifyUserInfoEntry item is added to the list,
- * it should not be g_free()'d by the caller; PurpleNotifyUserInfo will g_free it when destroyed.
+ * Retrieve the array of PurpleNotifyUserInfoEntry objects from a
+ * PurpleNotifyUserInfo
  *
- * To remove a PurpleNotifyUserInfoEntry, use purple_notify_user_info_remove_entry(). Do not use the GList directly.
+ * This GList may be manipulated directly with normal GList functions such
+ * as g_list_insert(). Only PurpleNotifyUserInfoEntry are allowed in the
+ * list.  If a PurpleNotifyUserInfoEntry item is added to the list, it
+ * should not be g_free()'d by the caller; PurpleNotifyUserInfo will g_free
+ * it when destroyed.
  *
- * @param user_info          The PurpleNotifyUserInfo
+ * To remove a PurpleNotifyUserInfoEntry, use
+ * purple_notify_user_info_remove_entry(). Do not use the GList directly.
  *
- * @constreturn              A GList of PurpleNotifyUserInfoEntry objects
+ * @param user_info  The PurpleNotifyUserInfo
+ *
+ * @constreturn A GList of PurpleNotifyUserInfoEntry objects
  */
 GList *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
 
 /**
- * Create a textual representation of a PurpleNotifyUserInfo, separating entries with newline
+ * Create a textual representation of a PurpleNotifyUserInfo, separating
+ * entries with newline
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param newline            The separation character
+ * @param user_info  The PurpleNotifyUserInfo
+ * @param newline    The separation character
  */
 char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
 
@@ -524,46 +531,58 @@
  * Add a label/value pair to a PurpleNotifyUserInfo object.
  * PurpleNotifyUserInfo keeps track of the order in which pairs are added.
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
- *                           If NULL, value will be displayed without a label.
- * @param value              The value, which might be displayed by a UI after the label.
- *                           If NULL, label will still be displayed; the UI should then treat label as independent
- *                           and not include a colon if it would otherwise.
+ * @param user_info  The PurpleNotifyUserInfo
+ * @param label      A label, which for example might be displayed by a
+ *                   UI with a colon after it ("Status:"). Do not include
+ *                   a colon.  If NULL, value will be displayed without a
+ *                   label.
+ * @param value      The value, which might be displayed by a UI after
+ *                   the label.  If NULL, label will still be displayed;
+ *                   the UI should then treat label as independent and not
+ *                   include a colon if it would otherwise.
  */
 void purple_notify_user_info_add_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 
 /**
  * Prepend a label/value pair to a PurpleNotifyUserInfo object
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
- *                           If NULL, value will be displayed without a label.
- * @param value              The value, which might be displayed by a UI after the label.
- *                           If NULL, label will still be displayed; the UI should then treat label as independent
- *                           and not include a colon if it would otherwise.
+ * @param user_info  The PurpleNotifyUserInfo
+ * @param label      A label, which for example might be displayed by a
+ *                   UI with a colon after it ("Status:"). Do not include
+ *                   a colon.  If NULL, value will be displayed without a
+ *                   label.
+ * @param value      The value, which might be displayed by a UI after
+ *                   the label.  If NULL, label will still be displayed;
+ *                   the UI should then treat label as independent and not
+ *                   include a colon if it would otherwise.
  */
 void purple_notify_user_info_prepend_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 
 /**
- * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object without freeing the entry.
+ * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object
+ * without freeing the entry.
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param user_info_entry    The PurpleNotifyUserInfoEntry
+ * @param user_info        The PurpleNotifyUserInfo
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
  */
 void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
+
 /**
  * Create a new PurpleNotifyUserInfoEntry
  *
- * If added to a PurpleNotifyUserInfo object, this should not be free()'d, as PurpleNotifyUserInfo will do so
- * when destroyed.  purple_notify_user_info_add_pair() and purple_notify_user_info_prepend_pair() are convenience
- * methods for creating entries and adding them to a PurpleNotifyUserInfo.
+ * If added to a PurpleNotifyUserInfo object, this should not be free()'d,
+ * as PurpleNotifyUserInfo will do so when destroyed.
+ * purple_notify_user_info_add_pair() and
+ * purple_notify_user_info_prepend_pair() are convenience methods for
+ * creating entries and adding them to a PurpleNotifyUserInfo.
  *
- * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
- *                           If NULL, value will be displayed without a label.
- * @param value              The value, which might be displayed by a UI after the label.
- *                           If NULL, label will still be displayed; the UI should then treat label as independent
- *                           and not include a colon if it would otherwise.
+ * @param label  A label, which for example might be displayed by a UI
+ *               with a colon after it ("Status:"). Do not include a
+ *               colon.  If NULL, value will be displayed without a label.
+ * @param value  The value, which might be displayed by a UI after the
+ *               label.  If NULL, label will still be displayed; the UI
+ *               should then treat label as independent and not include a
+ *               colon if it would otherwise.
  *
  * @result A new PurpleNotifyUserInfoEntry
  */
@@ -572,71 +591,74 @@
 /**
  * Add a section break.  A UI might display this as a horizontal line.
  *
- * @param user_info          The PurpleNotifyUserInfo
+ * @param user_info  The PurpleNotifyUserInfo
  */
 void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
 
 /**
  * Prepend a section break.  A UI might display this as a horizontal line.
  *
- * @param user_info          The PurpleNotifyUserInfo
+ * @param user_info  The PurpleNotifyUserInfo
  * @since 2.5.0
  */
 void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
-	
+
 /**
- * Add a section header.  A UI might display this in a different font from other text.
+ * Add a section header.  A UI might display this in a different font
+ * from other text.
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param label              The name of the section
+ * @param user_info  The PurpleNotifyUserInfo
+ * @param label      The name of the section
  */
 void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
-	
+
 /**
- * Prepend a section header.  A UI might display this in a different font from other text.
+ * Prepend a section header.  A UI might display this in a different font
+ * from other text.
  *
- * @param user_info          The PurpleNotifyUserInfo
- * @param label              The name of the section
+ * @param user_info  The PurpleNotifyUserInfo
+ * @param label      The name of the section
  * @since 2.5.0
  */
 void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
-	
+
 /**
- * Remove the last item which was added to a PurpleNotifyUserInfo. This could be used to remove a section header which is not needed.
+ * Remove the last item which was added to a PurpleNotifyUserInfo. This
+ * could be used to remove a section header which is not needed.
  */
 void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
 
 /**
  * Get the label for a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
  *
- * @result                    The label
+ * @return  The label
  */
 const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
 
 /**
  * Set the label for a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
- * @param label			      The label
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
+ * @param label            The label
  */
 void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
 
 /**
  * Get the value for a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
  *
- * @result                    The value
+ * @result  The value
  */
 const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
 
 /**
  * Set the value for a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
- * @param value				  The value
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
+ * @param value            The value
  */
 void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
 
@@ -644,17 +666,17 @@
 /**
  * Get the type of a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
  *
- * @result					  The PurpleNotifyUserInfoEntryType
+ * @return  The PurpleNotifyUserInfoEntryType
  */
 PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry);
 
 /**
  * Set the type of a PurpleNotifyUserInfoEntry
  *
- * @param user_info_entry     The PurpleNotifyUserInfoEntry
- * @param type				  The PurpleNotifyUserInfoEntryType
+ * @param user_info_entry  The PurpleNotifyUserInfoEntry
+ * @param type             The PurpleNotifyUserInfoEntryType
  */
 void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry,
 										  PurpleNotifyUserInfoEntryType type);