# HG changeset patch # User Jacob Dawid # Date 1313536737 -7200 # Node ID d3527a9dfe2770cd18eebcbd6ae438e63d83f441 # Parent fd31226d4c3a5a1b688d6a6a92a199d1196cd99b Added doxygen comments for IRC interface. diff -r fd31226d4c3a -r d3527a9dfe27 gui/src/qirc/IRCClientImpl.cpp --- a/gui/src/qirc/IRCClientImpl.cpp Wed Aug 17 00:36:10 2011 +0200 +++ b/gui/src/qirc/IRCClientImpl.cpp Wed Aug 17 01:18:57 2011 +0200 @@ -144,7 +144,7 @@ } -IRCChannelProxy::IRCChannelProxy (IRCClientInterface *clientInterface, const QString& channelName, QObject *parent) +IRCChannelProxyImpl::IRCChannelProxyImpl (IRCClientInterface *clientInterface, const QString& channelName, QObject *parent) : IRCChannelProxyInterface (clientInterface, channelName, parent), m_clientInterface (clientInterface) { @@ -152,32 +152,32 @@ } QTextDocument * -IRCChannelProxy::conversationModel () +IRCChannelProxyImpl::conversationModel () { return &m_conversationModel; } QStringListModel * -IRCChannelProxy::userListModel () +IRCChannelProxyImpl::userListModel () { return &m_userListModel; } QString -IRCChannelProxy::channelName () +IRCChannelProxyImpl::channelName () { return m_channelName; } void -IRCChannelProxy::setNickList (const QStringList &nickList) +IRCChannelProxyImpl::setNickList (const QStringList &nickList) { m_userList = nickList; m_userListModel.setStringList (nickList); } void -IRCChannelProxy::sendMessage (const QString& message) +IRCChannelProxyImpl::sendMessage (const QString& message) { QStringList arguments; arguments << m_channelName; @@ -186,14 +186,14 @@ } void -IRCChannelProxy::sendJoinRequest () +IRCChannelProxyImpl::sendJoinRequest () { m_clientInterface->sendIRCCommand (IRCCommand::Join, QStringList (m_channelName)); } void -IRCChannelProxy::leave (const QString& reason) +IRCChannelProxyImpl::leave (const QString& reason) { Q_UNUSED (reason); } @@ -264,7 +264,7 @@ IRCClientImpl::ircChannelProxy (const QString &channel) { if (!m_channels.contains (channel)) - m_channels[channel] = new IRCChannelProxy(this, channel); + m_channels[channel] = new IRCChannelProxyImpl(this, channel); return m_channels[channel]; } diff -r fd31226d4c3a -r d3527a9dfe27 gui/src/qirc/IRCClientImpl.h --- a/gui/src/qirc/IRCClientImpl.h Wed Aug 17 00:36:10 2011 +0200 +++ b/gui/src/qirc/IRCClientImpl.h Wed Aug 17 01:18:57 2011 +0200 @@ -26,6 +26,10 @@ #include #include "IRCClientInterface.h" +/** + * \namespace IRCCommand + * This namespace includes all IRC commands. + */ namespace IRCCommand { const QString Password = "PASS"; @@ -82,6 +86,10 @@ const QString IsOn = "ISON"; }; +/** + * \namespace IRCReply + * This namespace includes all numeric IRC replies. + */ namespace IRCReply { const int Welcome = 1; @@ -169,6 +177,10 @@ const int TryAgain = 263; }; +/** + * \namespace IRCError + * This namespace includes all numeric IRC errors. + */ namespace IRCError { const int NoSuchNick = 401; @@ -226,6 +238,12 @@ const int UsersDontMatch = 502; }; +/** + * \class IRCServerMessage + * The IRCServerMessage class is a wrapper for server messages. + * It parses the server message into its single bits and makes these + * available through Getter-methods. + */ class IRCServerMessage { public: @@ -253,11 +271,16 @@ QStringList m_parameters; }; -class IRCChannelProxy : public IRCChannelProxyInterface +/** + * \class IRCChannelProxyImpl + * Implements a handle to an IRC channel. This is usually provided by the + * the IRC client class. + */ +class IRCChannelProxyImpl : public IRCChannelProxyInterface { Q_OBJECT public: - IRCChannelProxy (IRCClientInterface *clientInterface, const QString& channelName, QObject *parent = 0); + IRCChannelProxyImpl (IRCClientInterface *clientInterface, const QString& channelName, QObject *parent = 0); QTextDocument *conversationModel (); QStringListModel *userListModel (); QString channelName (); @@ -275,6 +298,12 @@ IRCClientInterface *m_clientInterface; }; +/** + * \class IRCClientImpl + * Implements an IRC client. This class can maintain a connection to one server. + * In order to interface an IRC channel, use the ircChannelProxy-method to retrieve + * a handle. + */ class IRCClientImpl : public IRCClientInterface { Q_OBJECT diff -r fd31226d4c3a -r d3527a9dfe27 gui/src/qirc/IRCClientInterface.h --- a/gui/src/qirc/IRCClientInterface.h Wed Aug 17 00:36:10 2011 +0200 +++ b/gui/src/qirc/IRCClientInterface.h Wed Aug 17 01:18:57 2011 +0200 @@ -26,6 +26,10 @@ #include class IRCClientInterface; +/** + * \class IRCChannelProxyInterface + * Interface for a handle to an IRC channel. + */ class IRCChannelProxyInterface : public QObject { Q_OBJECT @@ -33,12 +37,34 @@ IRCChannelProxyInterface (IRCClientInterface *, const QString&, QObject *parent = 0) : QObject (parent) { } virtual ~IRCChannelProxyInterface () { } + /** Returns the conversation model part. */ virtual QTextDocument *conversationModel () = 0; + + /** Returns a string list model for the user list. */ virtual QStringListModel *userListModel () = 0; + + /** Returns the name of this channel. */ virtual QString channelName () = 0; + + /** + * Overwrites the current nick list by settings a new nick list. + * \arg nickList The new nick list to set. + */ virtual void setNickList (const QStringList& nickList) = 0; + + /** + * Sends a public message onto this channel. + * \arg message The message that should be sent. + */ virtual void sendMessage (const QString& message) = 0; + + /** Requests to join this channel. */ virtual void sendJoinRequest () = 0; + + /** + * Requests to leave this channel. + * \arg reason Reason for leaving the channel. + */ virtual void leave (const QString& reason) = 0; }; @@ -53,35 +79,139 @@ IRCClientInterface (QObject *parent = 0) : QObject (parent) { } virtual ~IRCClientInterface () { } + /** Returns the current nickname of this client. */ virtual const QString& nickname () = 0; + + /** Returns true if connected to the server. */ virtual bool isConnected () = 0; + + /** + * Returns true if logged in to the server. + * Note: There is a small difference between isConnected and isLoggedIn. + * isConnected returns true if there is a physical connection to the server. + * isLoggedIn only returns true if the server has already accepted you + * and you are ready to log into channels. + */ virtual bool isLoggedIn () = 0; + + /** Returns the current host address. */ virtual const QHostAddress& host() = 0; + + /** Returns the current port. */ virtual int port() = 0; + + /** + * Returns a handle to an IRC channel. + * Note: Retrieving a handle does not mean you have joined this channel. + * \arg channel The channel to retrieve a handle for. + */ virtual IRCChannelProxyInterface *ircChannelProxy(const QString& channel) = 0; + + /** + * Send an IRC command to the server. + * \arg command Command to send. + * \arg arguments Arguments to send. + */ virtual void sendIRCCommand (const QString& command, const QStringList& arguments) = 0; public slots: - // Connection state: + /** + * Connects to a host. + * \arg host The host to connect tp. + * \arg port The port on which to connect to the host. + * \arg initialNick The initial nick to use when attempting to login. + */ virtual void connectToHost (const QHostAddress& host, int port, const QString& initialNick) = 0; + + /** Disconnects from the host. */ virtual void disconnect () = 0; + + /** Reconnects to the host. */ virtual void reconnect () = 0; + /** + * Sends a request to change the nickname. + * \arg nickname The new nickname to be requested. + */ virtual void sendNicknameChangeRequest (const QString& nickname) = 0; + + /** + * Sends a private message. + * \arg recipient The nickname or channel that message should be sent to. + * \arg message The message that should be sent. + */ virtual void sendPrivateMessage (const QString& recipient, const QString& message) = 0; signals: + /** + * Sent upon the arrival of a new message. + * \arg channel The channel this message was sent from. + * \arg sender The nickname of the sender. + * \arg message The message that has been sent. + */ void newMessage (const QString& channel, const QString& sender, const QString& message); - void connected (const QString& server); - void disconnected (); - void error (const QString& message); - void notification (const QString& sender, const QString& message); void message (const QString& channel, const QString& sender, const QString& message); + + /** + * Sent when the connection to a server has been established. + * \arg server The name of the server that the connection has been established to. + */ + void connected (const QString& server); + + /** Sent when the connection to the server has been interrupted. */ + void disconnected (); + + /** + * Sent when an error occurs. + * \arg message A descriptive message of the error that occured. + */ + void error (const QString& message); + + /** + * Sent when a notification arrives. + * \arg sender The source of the notification. + * \arg message The notification. + */ + void notification (const QString& sender, const QString& message); + + /** + * Sent when a nickname changed. + * \arg oldNick The previous nickname. + * \arg newNick The new nickname. + */ void nicknameChanged (const QString& oldNick, const QString& newNick); + + /** + * Sent when the nickname of this client changed. + * \arg nick The new nickname of this client. + */ void userNicknameChanged (const QString& nick); + + /** + * Sent when a user has joined a channel. + * \arg nick Nickname of the user that joined the channel. + * \arg channel Channel that this user joined. + */ void userJoined (const QString& nick, const QString& channel); + + /** + * Sent when a user quits. + * \arg nick Nickname of the user that quit. + * \arg reason Reason of the user to quit. + */ void userQuit (const QString& nick, const QString& reason); + + /** + * Sent when a user logged in. + * \arg nick The nickname of the user that logged in. + */ void loggedIn (const QString& nick); + + /** + * Sent when the server provides a userlist for a channel. + * \arg channel The channel that userlist applies to. + * \arg list The actual userlist. + */ void userList (const QString& channel, const QStringList& list); };