changeset 6605:943b03bcecf5

[gaim-migrate @ 7129] Added some signal documentation. The conversation signal docs are taking forever. Who wants to help? :) committer: Tailor Script <[e-mail]>

--- a/Doxyfile.in	Sun Aug 24 05:49:50 2003 +0000
+++ b/Doxyfile.in	Sun Aug 24 06:32:28 2003 +0000
@@ -262,7 +262,14 @@
 # will result in a user-defined paragraph with heading "Side Effects:". 
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = "signal=@xrefitem signal \"Signals\" \"Signals\" @b"
+ALIASES                = "signal=- @ref"
+ALIASES               += "signaldef=@section"
+ALIASES               += "endsignaldef=@endsection"
+ALIASES               += "signalproto=@code"
+ALIASES               += "endsignalproto=@endcode"
+ALIASES               += "signaldesc=@par Description:\n"
+ALIASES               += "signals=@b Signals:\n"
+ALIASES               += "endsignals="
 
 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/account-signals.dox	Sun Aug 24 06:32:28 2003 +0000
@@ -0,0 +1,65 @@
+/** @page account-signals Account Signals
+
+ @signals
+  @signal account-away
+  @signal account-connecting
+  @signal account-setting-info
+  @signal account-set-info
+ @endsignals
+
+ <hr>
+
+ @signaldef account-away
+  @signalproto
+void (*account_away)(GaimAccount *account, const char *state, const char *message);
+  @endsignalproto
+  @param account The account that went away.
+  @param state   The away state.
+  @param message The away message.
+  @signaldesc
+   Emitted when an account goes away.
+ @endsignaldef
+
+ @signaldef account-connecting
+  @signalproto
+void (*account_connecting)(GaimAccount *account);
+  @endsignalproto
+  @param account The account in the process of connecting.
+  @signaldesc
+   This is called when an account is in the process of connecting.
+ @endsignaldef
+
+ @signaldef account-setting-info
+  @signalproto
+void (*account_setting_info)(GaimAccount *account, const char *new_info);
+  @endsignalproto
+  @param account  The account that the info will be set on.
+  @param new_info The new information to set.
+  @signaldesc
+   Emitted when a user is about to send his new user info, or
+   profile, to the server.
+ @endsignaldef
+
+ @signaldef account-set-info
+  @signalproto
+void (*account_set_info)(GaimAccount *account, const char *new_info);
+  @endsignalproto
+  @param account  The account that the info was set on.
+  @param new_info The new information set.
+  @signaldesc
+   Emitted when a user sent his new user info, or profile, to the server.
+ @endsignaldef
+
+ @signaldef account-warned
+  @signalproto
+void (*account_warned)(GaimAccount *account, const char *warner, int level);
+  @endsignalproto
+  @param account The account that was warned.
+  @param warner  The screenname of the user that warned the account.
+  @param level   The new warning level.
+  @signaldesc
+   Emitted when an account got warned.
+ @endsignaldef
+
+ */
+// vim: syntax=c tw=75 et

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/blist-signals.dox	Sun Aug 24 06:32:28 2003 +0000
@@ -0,0 +1,78 @@
+/** @page blist-signals Buddy List Signals
+
+ @signals
+  @signal buddy-away
+  @signal buddy-back
+  @signal buddy-idle
+  @signal buddy-unidle
+  @signal buddy-signed-on
+  @signal buddy-signed-off
+  @signal update-idle
+ @endsignals
+
+ <hr>
+
+ @signaldef buddy-away
+  @signalproto
+void (*buddy_away)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that went away.
+  @signaldesc
+   Emitted when a buddy on your buddy list goes away.
+ @endsignaldef
+
+ @signaldef buddy-back
+  @signalproto
+void (*buddy_back)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that came back from being away.
+  @signaldesc
+   Emitted when a buddy on your buddy list comes back from being away.
+ @endsignaldef
+
+ @signaldef buddy-idle
+  @signalproto
+void (*buddy_idle)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that became idle.
+  @signaldesc
+   Emitted when a buddy on your buddy list becomes idle.
+ @endsignaldef
+
+ @signaldef buddy-unidle
+  @signalproto
+void (*buddy_unidle)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that returned from being idle.
+  @signaldesc
+   Emitted when a buddy on your buddy list returns from being idle.
+ @endsignaldef
+
+ @signaldef buddy-signed-on
+  @signalproto
+void (*buddy_signed_on)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that signed on.
+  @signaldesc
+   Emitted when a buddy on your buddy list signs on.
+ @endsignaldef
+
+ @signaldef buddy-signed-off
+  @signalproto
+void (*buddy_signed_off)(struct buddy *buddy);
+  @endsignalproto
+  @param buddy The buddy that signed off.
+  @signaldesc
+   Emitted when a buddy on your buddy list signs off.
+ @endsignaldef
+
+ @signaldef update-idle
+  @signalproto
+void (*update_idle)();
+  @endsignalproto
+  @signaldesc
+   Emitted when the buddy list is refreshed and the idle times are updated.
+ @endsignaldef
+
+ */
+// vim: syntax=c tw=75 et

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conversation-signals.dox	Sun Aug 24 06:32:28 2003 +0000
@@ -0,0 +1,268 @@
+/** @page conversation-signals Conversation Signals
+
+ @signals
+  @signal displaying-im-msg
+  @signal displayed-im-msg
+  @signal sending-im-msg
+  @signal sent-im-msg
+  @signal received-im-msg
+  @signal displaying-chat-msg
+  @signal displayed-chat-msg
+  @signal sending-chat-msg
+  @signal sent-chat-msg
+  @signal received-chat-msg
+  @signal conversation-switching
+  @signal conversation-switched
+  @signal conversation-created
+  @signal deleting-conversation
+  @signal buddy-typing
+  @signal chat-buddy-joining
+  @signal chat-buddy-joined
+  @signal chat-buddy-leaving
+  @signal chat-buddy-left
+  @signal chat-inviting-user
+  @signal chat-invited-user
+  @signal chat-invited
+  @signal chat-joined
+  @signal chat-left
+ @endsignals
+
+ @signaldef displaying-im-msg
+  @signalproto
+gboolean (*displaying_im_msg)(GaimAccount *account, char **message);
+  @endsignalproto
+  @param account The account the message is being displayed on.
+  @param message A pointer to the message that will be displayed.
+  @signaldesc
+   Emitted just before a message is displayed in an IM conversation.
+   @a message is a pointer to a string, so the plugin can replace the
+   message that will be displayed. This can also be used to cancel displaying
+   a message by returning @c TRUE.
+  @note
+   Make sure to free @a *message before you replace it!
+  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @endsignaldef
+
+ @signaldef displayed-im-msg
+  @signalproto
+void (*displayed_im_msg)(GaimAccount *account, const char *message);
+  @endsignalproto
+  @param account The account the message was displayed on.
+  @param message The message that was displayed.
+  @signaldesc
+   Emitted after a message is displayed in an IM conversation.
+ @endsignaldef
+
+ @signaldef sending-im-msg
+  @signalproto
+void (*sending_im_msg)(GaimAccount *account, const char *receiver, char **message);
+  @endsignalproto
+  @param conv     The account the message is being sent on.
+  @param receiver The username of the receiver.
+  @param message  A pointer to the outgoing message. This can be modified.
+  @signaldesc
+   Emitted before sending an IM to a user. @a message is a pointer to the
+   message string, so the plugin can replace the message before being sent.
+  @note
+   Make sure to free @a *message before you replace it!
+ @endsignaldef
+
+ @signaldef sent-im-msg
+  @signalproto
+void (*sent_im_msg)(GaimAccount *account, const char *receiver, const char *message);
+  @endsignalproto
+  @param account  The account the message was sent on.
+  @param receiver The username of the receiver.
+  @param message  The message that was sent.
+  @signaldesc
+   Emitted after sending an IM to a user.
+ @endsignaldef
+
+ @signaldef received-im-msg
+  @signalproto
+gboolean (*received_im_msg)(GaimAccount *account, char **sender, char **message, int *flags);
+  @endsignalproto
+  @param account The account the message was received on.
+  @param sender  A pointer to the username of the sender.
+  @param message A pointer to the message that was sent.
+  @signaldesc
+   Emitted when an IM is received. The callback can replace the name of the
+   sender, the message, or the flags by modifying the pointer to the
+   strings and integer. This can also be used to cancel a message by
+   returning @c TRUE.
+  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @endsignaldef
+
+ @signaldef displaying-chat-msg
+  @signalproto
+void (*displaying-chat-msg)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef displayed-chat-msg
+  @signalproto
+void (*displayed-chat-msg)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef sending-chat-msg
+  @signalproto
+void (*sending-chat-msg)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef sent-chat-msg
+  @signalproto
+void (*sent-chat-msg)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef received-chat-msg
+  @signalproto
+void (*received-chat-msg)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef conversation-switching
+  @signalproto
+void (*conversation-switching)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef conversation-switched
+  @signalproto
+void (*conversation-switched)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef conversation-created
+  @signalproto
+void (*conversation-created)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef deleting-conversation
+  @signalproto
+void (*deleting-conversation)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef buddy-typing
+  @signalproto
+void (*buddy-typing)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-buddy-joining
+  @signalproto
+void (*chat-buddy-joining)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-buddy-joined
+  @signalproto
+void (*chat-buddy-joined)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-buddy-leaving
+  @signalproto
+void (*chat-buddy-leaving)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-buddy-left
+  @signalproto
+void (*chat-buddy-left)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-inviting-user
+  @signalproto
+void (*chat-inviting-user)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-invited-user
+  @signalproto
+void (*chat-invited-user)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-invited
+  @signalproto
+void (*chat-invited)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-joined
+  @signalproto
+void (*chat-joined)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+ @signaldef chat-left
+  @signalproto
+void (*chat-left)(GaimConversation *conv);
+  @endsignalproto
+  @param conv The conversation.
+  @signaldesc
+   
+ @endsignaldef
+
+*/
+// vim: syntax=c tw=75 et

--- a/src/account.h	Sun Aug 24 05:49:50 2003 +0000
+++ b/src/account.h	Sun Aug 24 06:32:28 2003 +0000
@@ -19,6 +19,8 @@
  * 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 account-signals
  */
 #ifndef _GAIM_ACCOUNTS_H_
 #define _GAIM_ACCOUNTS_H_

--- a/src/connection.h	Sun Aug 24 05:49:50 2003 +0000
+++ b/src/connection.h	Sun Aug 24 06:32:28 2003 +0000
@@ -20,10 +20,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  *
- * @signal signing-on (GaimConnection *gc)
- * @signal signed-on (GaimConnection *gc)
- * @signal signing-off (GaimConnection *gc)
- * @signal signed-off (GaimConnection *gc)
+ * @see @ref connection-signals
  */
 #ifndef _GAIM_CONNECTION_H_
 #define _GAIM_CONNECTION_H_

--- a/src/conversation.c	Sun Aug 24 05:49:50 2003 +0000
+++ b/src/conversation.c	Sun Aug 24 06:32:28 2003 +0000
@@ -16,7 +16,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
- *
  */
 #include "internal.h"
 #include "blist.h"

--- a/src/conversation.h	Sun Aug 24 05:49:50 2003 +0000
+++ b/src/conversation.h	Sun Aug 24 06:32:28 2003 +0000
@@ -20,30 +20,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  *
- * @signal displaying-im-msg
- * @signal displayed-im-msg
- * @signal sending-im-msg
- * @signal sent-im-msg
- * @signal received-im-msg
- * @signal displaying-chat-msg
- * @signal displayed-chat-msg
- * @signal sending-chat-msg
- * @signal sent-chat-msg
- * @signal received-chat-msg
- * @signal conversation-switching
- * @signal conversation-switched
- * @signal conversation-created
- * @signal deleting-conversation
- * @signal buddy-typing
- * @signal chat-buddy-joining
- * @signal chat-buddy-joined
- * @signal chat-buddy-leaving
- * @signal chat-buddy-left
- * @signal chat-inviting-user
- * @signal chat-invited-user
- * @signal chat-invited
- * @signal chat-joined
- * @signal chat-left
+ * @see @ref conversation-signals
  */
 #ifndef _GAIM_CONVERSATION_H_
 #define _GAIM_CONVERSATION_H_