# HG changeset patch
# User Christian Hammond <chipx86@chipx86.com>
# Date 1062566464 0
# Node ID 41120df7ed943f9ba4cf26f608a30134449f8c81
# Parent  3cc4d5e55a691c5d7a35e843652b8025e694d958
[gaim-migrate @ 7247]
Fixed documentation errors so Doxygen no longer complains.

committer: Tailor Script <tailor@pidgin.im>

diff -r 3cc4d5e55a69 -r 41120df7ed94 Doxyfile.in
--- a/Doxyfile.in	Wed Sep 03 04:49:24 2003 +0000
+++ b/Doxyfile.in	Wed Sep 03 05:21:04 2003 +0000
@@ -264,7 +264,7 @@
 
 ALIASES                = "signal=- @ref"
 ALIASES               += "signaldef=@section"
-ALIASES               += "endsignaldef=@endsection"
+ALIASES               += "endsignaldef="
 ALIASES               += "signalproto=@code"
 ALIASES               += "endsignalproto=@endcode"
 ALIASES               += "signaldesc=@par Description:\n"
diff -r 3cc4d5e55a69 -r 41120df7ed94 doc/PERL-HOWTO.dox
--- a/doc/PERL-HOWTO.dox	Wed Sep 03 04:49:24 2003 +0000
+++ b/doc/PERL-HOWTO.dox	Wed Sep 03 05:21:04 2003 +0000
@@ -9,7 +9,6 @@
   functions. However, with the latest changes to Gaim's perl API, a much
   larger part of Gaim is now open. In time, even such things as Gtk+
   preference panes for perl scripts will be possible.
- @endsection
 
  @section first-script Writing your first perl script
   Enough of that. You want to know how to write a perl script, right?
@@ -80,7 +79,6 @@
            okay, as long as they're set to be local. Bad Things (TM) can
            happen if you don't follow this simple instruction.
 
- @endsection
 
  @section Timeouts
   One feature useful to many perl plugin writers are timeouts. Timeouts allow
@@ -131,7 +129,6 @@
 
   The data parameter is optional. If you don't have data to pass to the
   callback, simply omit the parameter.
- @endsection
 
  @section Signals
   Signals are how gaim plugins get events. There are a number of
@@ -163,18 +160,15 @@
 
   Like timeouts, the callback can be an embedded subroutine, and also
   like timeouts, the data parameter can be omitted.
- @endsection
 
  @section Notes
   The API in perl is very similar to Gaim's C API. The functions have been
   gathered into packages, but most are the same, and the documentation can
   be a big help at times.
- @endsection
 
  @section Resources
   @see Signals
   @see Perl API Reference
- @endsection
 
 */
 // vim: syntax=c tw=75 et
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/account.h
--- a/src/account.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/account.h	Wed Sep 03 05:21:04 2003 +0000
@@ -145,8 +145,8 @@
 /**
  * Sets the account's user information
  *
- * @param account The account.
- * @param info    The user information.
+ * @param account   The account.
+ * @param user_info The user information.
  */
 void gaim_account_set_user_info(GaimAccount *account, const char *user_info);
 
@@ -251,7 +251,7 @@
  * @param value   The setting's value.
  */
 void gaim_account_set_string(GaimAccount *account, const char *name,
-							 const char *string);
+							 const char *value);
 
 /**
  * Sets a protocol-specific boolean setting for an account.
@@ -283,7 +283,7 @@
  * @param value   The setting's value.
  */
 void gaim_account_set_ui_string(GaimAccount *account, const char *ui,
-								const char *name, const char *string);
+								const char *name, const char *value);
 
 /**
  * Sets a UI-specific boolean setting for an account.
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/blist.h
--- a/src/blist.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/blist.h	Wed Sep 03 05:21:04 2003 +0000
@@ -248,8 +248,8 @@
 /**
  * Updates a buddy's warning level.
  *
- * @param buddy  The buddy whose warning level has changed
- * @param evil   The warning level as an int from 0 to 100 (or higher, I guess... but that'd be weird)
+ * @param buddy   The buddy whose warning level has changed.
+ * @param warning The warning level as an int from 0 to 100.
  */
 void gaim_blist_update_buddy_evil(GaimBuddy *buddy, int warning);
 
@@ -351,9 +351,10 @@
  * group if node is NULL.  If both are NULL, the buddy will be added to
  * the "Buddies" group.
  *
- * @param buddy  The new buddy who gets added
- * @param group  The group to add the new buddy to.
- * @param node   The insertion point
+ * @param buddy   The new buddy who gets added
+ * @param contact The optional contact to place the buddy in.
+ * @param group   The group to add the new buddy to.
+ * @param node    The insertion point
  */
 void gaim_blist_add_buddy(GaimBuddy *buddy, GaimContact *contact, GaimGroup *group, GaimBlistNode *node);
 
@@ -494,7 +495,8 @@
 /**
  * Finds a chat by name.
  *
- * @param name The chat's name.
+ * @param account The chat's account.
+ * @param name    The chat's name.
  *
  * @return The chat, or @c NULL if the chat does not exist.
  */
@@ -521,8 +523,9 @@
 /**
  * Returns a list of accounts that have buddies in this group
  *
- * @param group   The group
- * @return        A list of gaim_accounts
+ * @param g The group
+ *
+ * @return A list of gaim_accounts
  */
 GSList *gaim_group_get_accounts(GaimGroup *g);
 
@@ -531,6 +534,8 @@
  *
  * @param g       The group to search through.
  * @param account The account.
+ *
+ * @return TRUE if there are any buddies in the group, or FALSE otherwise.
  */
 gboolean gaim_group_on_account(GaimGroup *g, GaimAccount *account);
 
@@ -616,7 +621,7 @@
 /**
  * Associates some data with the chat in the xml buddy list
  *
- * @param b      The chat the data is associated with
+ * @param c      The chat the data is associated with
  * @param key    The key used to retrieve the data
  * @param value  The data to set
  */
@@ -625,8 +630,9 @@
 /**
  * Retrieves data from the XML buddy list set by gaim_chat_set_setting())
  *
- * @param b      The chat to retrieve data from
+ * @param c      The chat to retrieve data from
  * @param key    The key to retrieve the data with
+ *
  * @return       The associated data or NULL if no data is associated
  */
 char *gaim_blist_chat_get_setting(GaimBlistChat *c, const char *key);
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/connection.h
--- a/src/connection.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/connection.h	Wed Sep 03 05:21:04 2003 +0000
@@ -19,8 +19,6 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
- *
- * @see @ref connection-signals
  */
 #ifndef _GAIM_CONNECTION_H_
 #define _GAIM_CONNECTION_H_
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/conversation.h
--- a/src/conversation.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/conversation.h	Wed Sep 03 05:21:04 2003 +0000
@@ -446,10 +446,10 @@
 /**
  * Creates a new conversation of the specified type.
  *
- * @param type The type of conversation.
- * @param user The account opening the conversation window on the gaim
- *             user's end.
- * @param name The name of the conversation.
+ * @param type    The type of conversation.
+ * @param account The account opening the conversation window on the gaim
+ *                user's end.
+ * @param name    The name of the conversation.
  *
  * @return The new conversation.
  */
@@ -542,7 +542,7 @@
 /**
  * Returns the specified conversation's title.
  *
- * @param win The conversation.
+ * @param conv The conversation.
  *
  * @return The title.
  */
@@ -581,7 +581,7 @@
  *
  * @param conv The conversation.
  *
- * @param The conversation's unseen state.
+ * @return The conversation's unseen state.
  */
 GaimUnseenState gaim_conversation_get_unseen(const GaimConversation *conv);
 
@@ -597,13 +597,16 @@
 /**
  * Enables or disables logging for this conversation.
  *
- * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
+ * @param conv The conversation.
+ * @param log  @c TRUE if logging should be enabled, or @c FALSE otherwise.
  */
 void gaim_conversation_set_logging(GaimConversation *conv, gboolean log);
 
 /**
  * Returns whether or not logging is enabled for this conversation.
  *
+ * @param conv The conversation.
+ *
  * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
  */
 gboolean gaim_conversation_is_logging(const GaimConversation *conv);
@@ -1159,6 +1162,7 @@
 /**
  * Adds a conversation placement function to the list of possible functions.
  *
+ * @param id   The unique ID of the placement function.
  * @param name The name of the function.
  * @param fnc  A pointer to the function.
  */
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/ft.h
--- a/src/ft.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/ft.h	Wed Sep 03 05:21:04 2003 +0000
@@ -531,7 +531,7 @@
 /**
  * Sets the UI operations structure to be used in all gaim file transfers.
  *
- * @param fnc The function.
+ * @param ops The UI operations structure.
  */
 void gaim_set_xfer_ui_ops(GaimXferUiOps *ops);
 
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/gtkinternal.h
--- a/src/gtkinternal.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/gtkinternal.h	Wed Sep 03 05:21:04 2003 +0000
@@ -1,11 +1,11 @@
 /**
- * @file internal.h Internal UI definitions and includes
+ * @file gtkinternal.h Internal UI definitions and includes
  * @ingroup gtkui
  *
  * gaim
  *
  * Copyright (C) 2003 Christian Hammond <chipx86@gnupdate.org>
- * 
+ *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/gtkutils.h
--- a/src/gtkutils.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/gtkutils.h	Wed Sep 03 05:21:04 2003 +0000
@@ -77,8 +77,8 @@
 /**
  * Surrounds the selected text with the specified font.
  *
- * @param conv The conversation.
- * @param font The new font.
+ * @param gtkconv The GTK+ conversation.
+ * @param font    The new font.
  */
 void gaim_gtk_set_font_face(GaimGtkConversation *gtkconv,
 							const char *font);
@@ -129,8 +129,8 @@
 /**
  * Toggles the sensitivity of all widgets in a pointer array.
  *
- * @param widget    @c NULL. Used for signal handlers.
- * @param to_toggle The array containing the widgets to toggle.
+ * @param w    @c NULL. Used for signal handlers.
+ * @param data The array containing the widgets to toggle.
  */
 void gtk_toggle_sensitive_array(GtkWidget *w, GPtrArray *data);
 
@@ -200,7 +200,7 @@
 /**
  * Creates a toolbar button with the stock icon.
  *
- * @param icon  The stock icon name.
+ * @param stock The stock icon name.
  *
  * @return The button.
  */
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/notify.h
--- a/src/notify.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/notify.h	Wed Sep 03 05:21:04 2003 +0000
@@ -133,7 +133,7 @@
  * @param subjects  The array of subjects.
  * @param froms     The array of from addresses.
  * @param tos       The array of destination addresses.
- * @param url       The URLs where the messages can be read.
+ * @param urls      The URLs where the messages can be read.
  * @param cb        The callback to call when the user closes
  *                  the notification.
  * @param user_data The data to pass to the callback.
@@ -158,6 +158,7 @@
  * @param text      The formatted text.
  * @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.
  */
@@ -169,7 +170,7 @@
  * Opens a URI or somehow presents it to the user.
  *
  * @param handle The plugin or connection handle.
- * @param url    The URI to display or go to.
+ * @param uri    The URI to display or go to.
  *
  * @return A UI-specific handle, if any. This may only be presented if
  *         the UI code displays a dialog instead of a webpage, or something
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/plugin.h
--- a/src/plugin.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/plugin.h	Wed Sep 03 05:21:04 2003 +0000
@@ -173,7 +173,7 @@
 /**
  * Attempts to load a previously probed plugin.
  *
- * @param filename The plugin's filename.
+ * @param plugin The plugin to load.
  *
  * @return @c TRUE if successful, or @c FALSE otherwise.
  *
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/pounce.h
--- a/src/pounce.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/pounce.h	Wed Sep 03 05:21:04 2003 +0000
@@ -123,7 +123,7 @@
  * @param pounce  The buddy pounce.
  * @param pouncee The buddy to pounce on.
  */
-void gaim_pounce_set_pouncee(GaimPounce *pounce, const char *buddy);
+void gaim_pounce_set_pouncee(GaimPounce *pounce, const char *pouncee);
 
 /**
  * Sets whether or not the pounce should be saved after execution.
@@ -263,7 +263,7 @@
  * Finds a pounce with the specified event(s) and buddy.
  *
  * @param pouncer The account to match against.
- * @param buddy   The buddy to match against.
+ * @param pouncee The buddy to match against.
  * @param events  The event(s) to match against.
  *
  * @return The pounce if found, or @c NULL otherwise.
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/privacy.h
--- a/src/privacy.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/privacy.h	Wed Sep 03 05:21:04 2003 +0000
@@ -45,7 +45,7 @@
  * Adds a user to the account's permit list.
  *
  * @param account    The account.
- * @Param name       The name of the user to add to the list.
+ * @param name       The name of the user to add to the list.
  * @param local_only If TRUE, only the local list is updated, and not
  *                   the server.
  *
@@ -58,7 +58,7 @@
  * Removes a user from the account's permit list.
  *
  * @param account    The account.
- * @Param name       The name of the user to add to the list.
+ * @param name       The name of the user to add to the list.
  * @param local_only If TRUE, only the local list is updated, and not
  *                   the server.
  *
@@ -71,7 +71,7 @@
  * Adds a user to the account's deny list.
  *
  * @param account    The account.
- * @Param name       The name of the user to add to the list.
+ * @param name       The name of the user to add to the list.
  * @param local_only If TRUE, only the local list is updated, and not
  *                   the server.
  *
@@ -84,7 +84,7 @@
  * Removes a user from the account's deny list.
  *
  * @param account    The account.
- * @Param name       The name of the user to add to the list.
+ * @param name       The name of the user to add to the list.
  * @param local_only If TRUE, only the local list is updated, and not
  *                   the server.
  *
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/proxy.h
--- a/src/proxy.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/proxy.h	Wed Sep 03 05:21:04 2003 +0000
@@ -88,38 +88,38 @@
 /**
  * Destroys a proxy information structure.
  *
- * @param proxy The proxy information structure to destroy.
+ * @param info The proxy information structure to destroy.
  */
 void gaim_proxy_info_destroy(GaimProxyInfo *info);
 
 /**
  * Sets the type of proxy.
  *
- * @param proxy The proxy information.
- * @param type  The proxy type.
+ * @param info The proxy information.
+ * @param type The proxy type.
  */
 void gaim_proxy_info_set_type(GaimProxyInfo *info, GaimProxyType type);
 
 /**
  * Sets the proxy host.
  *
- * @param proxy The proxy information.
- * @param host  The host.
+ * @param info The proxy information.
+ * @param host The host.
  */
 void gaim_proxy_info_set_host(GaimProxyInfo *info, const char *host);
 
 /**
  * Sets the proxy port.
  *
- * @param proxy The proxy information.
- * @param port  The port.
+ * @param info The proxy information.
+ * @param port The port.
  */
 void gaim_proxy_info_set_port(GaimProxyInfo *info, int port);
 
 /**
  * Sets the proxy username.
  *
- * @param proxy    The proxy information.
+ * @param info     The proxy information.
  * @param username The username.
  */
 void gaim_proxy_info_set_username(GaimProxyInfo *info, const char *username);
@@ -127,7 +127,7 @@
 /**
  * Sets the proxy password.
  *
- * @param proxy    The proxy information.
+ * @param info     The proxy information.
  * @param password The password.
  */
 void gaim_proxy_info_set_password(GaimProxyInfo *info, const char *password);
@@ -135,7 +135,7 @@
 /**
  * Returns the proxy's type.
  *
- * @param The proxy information.
+ * @param info The proxy information.
  *
  * @return The type.
  */
@@ -144,7 +144,7 @@
 /**
  * Returns the proxy's host.
  *
- * @param The proxy information.
+ * @param info The proxy information.
  *
  * @return The host.
  */
@@ -153,7 +153,7 @@
 /**
  * Returns the proxy's port.
  *
- * @param The proxy information.
+ * @param info The proxy information.
  *
  * @return The port.
  */
@@ -162,7 +162,7 @@
 /**
  * Returns the proxy's username.
  *
- * @param The proxy information.
+ * @param info The proxy information.
  *
  * @return The username.
  */
@@ -171,7 +171,7 @@
 /**
  * Returns the proxy's password.
  *
- * @param The proxy information.
+ * @param info The proxy information.
  *
  * @return The password.
  */
@@ -228,8 +228,8 @@
  *
  * @param account The account making the connection.
  * @param host    The destination host.
- * @Param port    The destination port.
- * @Param func    The input handler function.
+ * @param port    The destination port.
+ * @param func    The input handler function.
  * @param data    User-defined data.
  *
  * @return The socket handle.
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/prpl.h
--- a/src/prpl.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/prpl.h	Wed Sep 03 05:21:04 2003 +0000
@@ -333,7 +333,7 @@
 /**
  * Returns the plugin number for a protocol ID.
  *
- * @param protocol_id The protocol ID.
+ * @param id The protocol ID.
  *
  * @return The protocol ID for valid protocol plugin IDs.
  */
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/request.h
--- a/src/request.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/request.h	Wed Sep 03 05:21:04 2003 +0000
@@ -517,8 +517,8 @@
 /**
  * Sets the default value in an boolean field.
  *
- * @param field The field.
- * @param value The default value.
+ * @param field         The field.
+ * @param default_value The default value.
  */
 void gaim_request_field_bool_set_default_value(GaimRequestField *field,
 											   gboolean default_value);
@@ -526,8 +526,8 @@
 /**
  * Sets the value in an boolean field.
  *
- * @param field         The field.
- * @param default_value The default value.
+ * @param field The field.
+ * @param value The value.
  */
 void gaim_request_field_bool_set_value(GaimRequestField *field,
 									   gboolean value);
@@ -536,7 +536,7 @@
  * Returns the default value in an boolean field.
  *
  * @param field The field.
- * 
+ *
  * @return The default value.
  */
 gboolean gaim_request_field_bool_get_default_value(
@@ -673,7 +673,7 @@
  * @param cancel_cb     The callback for the cancel button.
  * @param user_data     The data to pass to the callback.
  * @param choice_count  The number of choices.
- * @param choice        The choices.
+ * @param ...           The choices.
  *
  * @return A UI-specific handle.
  */
@@ -722,7 +722,7 @@
  * @param default_action The default value.
  * @param user_data      The data to pass to the callback.
  * @param action_count   The number of actions.
- * @param action         The first action.
+ * @param ...            A list of actions.
  *
  * @return A UI-specific handle.
  */
@@ -841,7 +841,7 @@
  * Returns the UI operations structure to be used when displaying a
  * request.
  *
- * @param ops The UI operations structure.
+ * @return The UI operations structure.
  */
 GaimRequestUiOps *gaim_get_request_ui_ops(void);
 
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/signals.h
--- a/src/signals.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/signals.h	Wed Sep 03 05:21:04 2003 +0000
@@ -44,12 +44,12 @@
 /**
  * Registers a signal in an instance.
  *
- * @param instance  The instance to register the signal for.
- * @param signal    The signal name.
- * @param marshal   The marshal function.
- * @param ret_value The return value type, or NULL for no return value.
- * @param num_types The number of values to be passed to the callbacks.
- * @param ...       The values to pass to the callbacks.
+ * @param instance   The instance to register the signal for.
+ * @param signal     The signal name.
+ * @param marshal    The marshal function.
+ * @param ret_value  The return value type, or NULL for no return value.
+ * @param num_values The number of values to be passed to the callbacks.
+ * @param ...        The values to pass to the callbacks.
  *
  * @return The signal ID local to that instance, or 0 if the signal
  *         couldn't be registered.
@@ -80,6 +80,7 @@
  *
  * @param instance   The instance the signal is registered to.
  * @param signal     The signal.
+ * @param ret_value  The return value from the last signal handler.
  * @param num_values The returned number of values.
  * @param values     The returned list of values.
  */
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/sslconn.h
--- a/src/sslconn.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/sslconn.h	Wed Sep 03 05:21:04 2003 +0000
@@ -78,18 +78,18 @@
  *
  * @return The number of bytes read.
  */
-size_t gaim_ssl_read(GaimSslConnection *gsc, void *data, size_t len);
+size_t gaim_ssl_read(GaimSslConnection *gsc, void *buffer, size_t len);
 
 /**
  * Writes data to an SSL connection.
  *
- * @param gsc  The SSL connection handle.
- * @param data The data to write.
- * @param len  The length of the data to write.
+ * @param gsc    The SSL connection handle.
+ * @param buffer The buffer to write.
+ * @param len    The length of the data to write.
  *
  * @return The number of bytes written.
  */
-size_t gaim_ssl_write(GaimSslConnection *gsc, const void *data, size_t len);
+size_t gaim_ssl_write(GaimSslConnection *gsc, const void *buffer, size_t len);
 
 /*@}*/
 
diff -r 3cc4d5e55a69 -r 41120df7ed94 src/util.h
--- a/src/util.h	Wed Sep 03 04:49:24 2003 +0000
+++ b/src/util.h	Wed Sep 03 05:21:04 2003 +0000
@@ -219,7 +219,7 @@
  *
  * @return The string with carriage returns.
  */
-char *add_cr(const char *);
+char *add_cr(const char *str);
 
 /**
  * Strips all linefeeds from a string.