// Define contents of the main page

/**
 * @mainpage KMess - MSN Messenger client for Linux
 * 
 * @section about About KMess
 *
 * KMess is a MSN Messenger client for Linux. It enables Linux users to chat
 * with friends online who are using MSN Messenger in Windows or Mac OS.
 * The strength of KMess is it's integration with the KDE desktop environment,
 * focus on MSN Messenger specific features and an easy-to-use interface.
 *
 *
 * @section intro About this documentation
 * This documentation is written towards developers, to be used
 * as reference manual when writing code for KMess.
 * As new developer, it's recommended to have a global understanding of
 * the class structure KMess uses. This API documentation was created to lower that bar,
 * so it becomes easier to contribute code back to KMess.
 * A global introduction to KMess development process can be found online at:
 * - http://trac.kmess.org/
 *
 * These pages document the classes and functions KMess is build from.
 * The documentation also provides insight in the relation and
 * interaction between classes, reasons behind a certain implementation,
 * and aids developers to determine how code can be written.
 * Because KMess is built on top of the KDE and Qt libraries,
 * it's important to have a general understanding of the KDE and Qt libraries too:
 * - http://api.kde.org/
 * - http://doc.trolltech.com/4.3/index.html
 *
 *
 * @section protocol About the MSN protocol
 * Most knowledge about the MSN protocol has been reverse engineered.
 * There is no official documentation about how things are supposed to operate,
 * and how clients should respond in certain situations.
 *
 * Parts of the protocol are being documentated in a wiki-style site at: http://msnpiki.msnfanatic.com/.
 * We also have a small introduction at http://trac.kmess.org/.
 * Other sites scattered arround the net also provide documentation about
 * specialized parts of the protocol. These sites are listed at our development page,
 * but hopefully this information will be merged with the msnpiki documentation soon.
 *
 * To monitor the data exchanged between clients and servers, we use network sniffers (Ethereal).
 * The debugging tools also help to see the exchanged data.
 *
 *
 * @section debugging Debugging practices
 * Working with an undocumented protocol also means developers need to take care of
 * situations that can't be forseen. It's impossible to make guesses about error handling;
 * e.g. having a list of things which the server may send differently.
 * Code needs to verify it's boundaries, and warn (e.g. with <code>kWarning()</code>)
 * when received data can't be processed correctly.
 *
 * The code is filled with assertion tests and strict validations of the data being parsed.
 * This is required to verify whether the application communicates with the servers as it should.
 * For example, an 'if-else-if' always ends with a final 'else' to trap unforceen situations.
 * The P2P classes contain lots of code to detect the exact message type received.
 * Whenever possible, try to reproduce errors to test the code throughly.
 *
 * To prevent crashes in unexpected situations, tests are added to detect null-pointers and warn appropriately.
 * As rule of thumb:
 * - Normal debugging messages are displayed with <code>kDebug()</code>.
 * - Serious errors are displayed with <code>kWarning()</code>.
 * - Debugging messages should only be displayed when the program is compiled in debug mode.
 * - Warning messages may also be displayed by the final packaged executable.
 * - Null pointers are checked using: <code>if(KMESS_NULL(..)) return;</code>.
 *
 * When KMess is compiled in debug mode, the debug code between the <code>\#ifdef KMESSTEST</code> and <code>\#ifdef KMESSDEBUG_...</code> statements will be compiled.
 * The macros for these statements are found in kmessdebug.h.
 * The debug mode can be enabled in two ways:
 * - in KDevelop, select the 'debug' build configuration.
 * - for manual compiling, use <code>CXXFLAGS="-g -ansi -pedantic -Wall" ./configure --enable-debug-output --build-type=debugfull</code>.
 *
 * The debug mode adds:
 * - filenames and line numbers to crash dumps.
 * - filenames and line numbers to the KMESS_NULL macro output.
 * - assertion tests to most functions.
 * - verbose messages so code execution can be traced.
 * - debug window to analyse the network traffic.
 *
 * A special KMessTest class can be used to create use-case tests. This class
 * can be activated by both disabling and uncommenting the various lines in main.cpp.
 */


// Define groups for API docs

/**
 * @defgroup Root main
 * @brief    The global user interface and data classes accessed by all other modules.
 * @todo     write detailed documentation
 *
 * The global user interface and data classes accessed by all other modules.
 */

/**
 * @defgroup Debug main - debugging
 * @brief    Global functions defined by kmessdebug.h
 *
 * When KMess is compiled in debug mode, the debug code between
 * the <code>\#ifdef KMESSTEST</code> and <code>\#ifdef KMESSDEBUG_...</code> statements will be compiled.
 * Most macro's are simple defines to enable debug output for certain classes.
 * Debug messages are outputed with <code>kDebug()</code>. For warnings visible to the end-user,
 * the <code>kWarning()</code> function is used instead. These warnings are not embedded in <code>\#ifdef</code> blocks.
 *
 * Macros are also use to optionally wrap function calls to handle debug output.
 * The <code>KMESS_NULL</code> macro is used to prevent crashes in unexpected situations.
 * It can be called as: <code>if(KMESS_NULL(..)) return;</code>. This will output the variable, filename and line numbers
 * when the given pointer is null.
 * To transfer data to the NetworkWindow, the <code>KMESS_NET_*</code> macro's are used.
 * When the support for the network window is disabled, these macros are empty defines, so no compiler errors occur.
 */

/**
 * @defgroup Chat chat
 * @brief    The user interface of the chat window and formatting of chat messages.
 * @todo     write detailed documentation
 */

/**
 * @defgroup Contact contact
 * @brief    The data classes for contact information.
 *
 * The contact classes store the information of the current contact list.
 * They are the "Model" part of the Model-View-Controller design.
 * The classes are updated by calls from the MsnNotificationConnection class
 * and other user interface classes. When an object property has changed,
 * signal will be fired so other user interface classes can update their views.
 *
 * For example, the Contact and Group classes are represented by
 * a ContactListViewItem and GroupListViewItem class respectively. 
 * The Contact class does not update the ContactListViewItem class directly.
 * Instead, each Contact only emits signals for the properties that change.
 * The ContactListViewItem class responds by updating it's view.
 * MSN Messenger supports the appearance of contacts in multiple groups,
 * so multiple ContactListViewItem classes may be created for one Contact class.
 */

/**
 * @defgroup Dialogs dialogs
 * @brief    The additional dialogs used in the application.
 * @todo     write detailed documentation
 */

/**
 * @defgroup NetworkCore network
 * @brief    Handing of standard network connections.
 *
 * The classes that handle the standard network connections.
 * For the standard chat services, MSN Messenger uses two:
 * - A notification server, handled by the MsnNotificationConnection class.
 * - A switchboard server, handled by the MsnSwitchboardConnection class.
 *
 * The notification connection is the primary connection.
 * All standard commands are sent to the notification server.
 * The notification connection receives updates about other contacts, and invitations to a chat. 
 * When the notification connection is disconnected, you're disconnected with the MSN Messenger service.
 * The connection is kept alive with 'PNG' packets to survive NAT router timeouts.
 *
 * When a chat is initiated, a connection is made to a switchboard server.
 * Both contacts enter the same chat session (chat room). The switchboard
 * room operates as a broadcast channel. All chat messages are echo-ed to the
 * other contacts in the chat session.
 *
 * To login to the MSN Messenger network, the passport login data
 * is transmitted to a special authentication server.
 * As of 'Passport 3.0', this is a SOAP webservice handled by the PassportLoginService class in the @link NetworkSoap network/soap @endlink directory.
 * The login results are used to sign-in at the notification server.
 *
 * In 1-on-1 chats, it's possible to invite the other
 * contact for peer-to-peer sessions, handled by classes in the @link Applications network/applications @endlink directory.
 * The application invitations may establish other connection types.
 * This functionality can be found in the @link NetworkExtra network/extra @endlink directory.
 */

/**
 * @defgroup Applications network/applications
 * @brief    Handlers for all kinds of invitation types.
 *
 * During the chat conversation, contacts may invite each other to start an application (like Netmeeting or a SIP-phone).
 * This framework is also used to exchange files, pictures and webcam data.
 * Each invitation type is implemented in a different class.
 * Depening on the invitation scheme, the classes either depend on MimeApplication or P2PApplication.
 * The common funtionality of both classes is implemented in the Application class.
 *
 * The old (pre 6.0) MSN Messenger clients use plain text MIME messages to exchange the invitation data.
 * As of MSN Messenger 6.0, application invitations are sent in a new P2P-style format.
 * The P2P-style invitations fix many shortcomings of the MIME-style invitation format.
 * They support a generic way to establish and terminate sessions,
 * transfer binary data, and move the session to a direct connection between both end-hosts.
 * The session may also be moved back to the switchboard server
 * when a direct connection was closed or could not be made.
 * They actually transent the Switchboard session they're started in.
 * Other Switchboard connections may be used to transmit the session data to the peer contact.
 *
 * The P2P-style invitations require a careful interaction between both clients.
 * The details of this communication is handled in the P2PApplication class.
 * To create new invitations, it's sufficient to derive from this class
 * and implement the few custom parts of the invitation.
 * While new invitations are easy to implement, the catch of often the encoded 'Context' field
 * in the invitation message, or the codecs data is exchanged with.
 * Such obstacles could make it difficult to implement new functionality.
 */

/**
 * @defgroup NetworkExtra network/extra
 * @brief    Additional network functionality used by the applications.
 *
 * A package for additional network functionality.
 * The functionality of this package is mostly used by the Application invitations during the chat session.
 * This includes functionality to create additional connections, and utility classes like XmlFunctions.
 * Due to linking issues, these classes have been moved out of the "Networking code package".
 *
 * For file transfers, two distict classes are provided.
 * Old (pre 6.0) MSN Messenger clients use the MsnFtpConnection to transfer files.
 * New clients use the MsnDirectConnection to transmit P2P-messages directly between end-hosts.
 * To support NAT-ed setups, clients attempt to connect to both the internal and external IP-address of a host.
 * The connection attempts are managed by the DirectConnectionPool class.
 * During the setup of a direct connection, both end-hosts may attempt to connect to each other.
 * The DirectConnectionBase implements a transparent handling of client/server sockets to
 * address this complexity.
 */

/**
 * @defgroup NetworkSoap network/soap
 * @brief    Webservice integration
 *
 * Recent MSN Messenger features use SOAP calls to request data from other servers.
 * This functionality is provided by the HttpSoapConnection and SoapMessage classes.
 * The upcoming Windows Live Messenger also uses SOAP to retrieve the the contact list data.
 * As of Qt 4, it will be possible to replace the SOAP classes with standard Qt classes.
 */

/**
 * @defgroup NetworkUPnP network/upnp
 * @brief    Universal Play & Play support, enables programmatic control of NAT-routers.
 *
 * Universal Plug & Play (or UPnP) is a technology to interact with home devices, like NAT-routers
 * (so-called Internet Gateway Devices). The message format resembles SOAP (and it's RPC calls) for some parts,
 * but also incorporates a common structure to resolve services/features of each device.
 * Each UPnP-enabled device has one service description, but may include services
 * to locate specialized functionality.
 *
 * In NAT-routers, UPnP can be used to request information, update settings, port mappings, and request event notifications.
 * This package implements the minimal functionality to query port mappings of UPnP-enabled NAT-routers.
 * The UPnP::Manager class is the central starting point which calls other classes underneath.
 *
 * UPnP-enabled devices can be detected with a SSDP broadcast, handled by the UPnP::SsdpConnection class.
 * The SSDP broadcast also specifies which device-type the system is looking for.
 * When an Internet Gateway Device (IGD) is detected, it will be queried with
 * the UPnP::IgdControlPoint class. The global service description and meta information of the device
 * is retrieved by the UPnP::RootService class.
 * Using the device information, the generic UPnP::Layer3ForwardingService can be located too.
 * This service can be called to locate the specific UPnP::WanConnectionService.
 * The UPnP::WanConnectionService allows clients to configure the WAN-connection settings and port mappings.
 */

/**
 * @defgroup Notification notification
 * @brief The baloon widget code.
 * @todo write detailed documentation
 */

/**
 * @defgroup Settings settings
 * @brief The setting dialog and setting panels.
 * @todo write detailed documentation
 */

/**
 * @defgroup Utils utils
 * @brief    Utility functions used by various classes.
 * @todo     write detailed documentation
 *
 * A package to store utility classes.
 * By keeping the utilities here, these classes won't clutter up other modules.
 */

