Merge remote-tracking branch 'gkiagia/service-side-docs'

Reviewed-by: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>

9 files changed, 1142 insertions, 0 deletions

diff --git a/TelepathyQt/abstract-adaptor.cpp b/TelepathyQt/abstract-adaptor.cpp
index e0847214..fa37a357 100644
--- a/TelepathyQt/abstract-adaptor.cpp
+++ b/TelepathyQt/abstract-adaptor.cpp
@@ -43,6 +43,30 @@ struct TP_QT_NO_EXPORT AbstractAdaptor::Private
     QObject *adaptee;
 };
 
+/**
+ * \class AbstractAdaptor
+ * \ingroup servicesideimpl
+ * \headerfile TelepathyQt/abstract-adaptor.h <TelepathyQt/AbstractAdaptor>
+ *
+ * \brief Base class for all the low-level service-side adaptors.
+ *
+ * This class serves as the parent for all the generated low-level service-side
+ * adaptors. Adaptors provide the interface of an object on the bus.
+ *
+ * The implementation of this interface should be provided in a special object
+ * called the adaptee. The adaptee is meant to provide properties, signals
+ * and slots that are connected automatically with the adaptor using Qt's meta-object
+ * system.
+ */
+
+/**
+ * Construct a new AbstractAdaptor that operates on the given
+ * \a dbusConnection and redirects calls to the given \a adaptee.
+ *
+ * \param dbusConnection The D-Bus connection to use.
+ * \param adaptee The class the provides the implementation of the calls.
+ * \param parent The QObject parent of this adaptor.
+ */
 AbstractAdaptor::AbstractAdaptor(const QDBusConnection &dbusConnection,
         QObject *adaptee, QObject *parent)
     : QDBusAbstractAdaptor(parent),
@@ -51,16 +75,30 @@ AbstractAdaptor::AbstractAdaptor(const QDBusConnection &dbusConnection,
     setAutoRelaySignals(false);
 }
 
+/**
+ * Class destructor.
+ */
 AbstractAdaptor::~AbstractAdaptor()
 {
     delete mPriv;
 }
 
+/**
+ * Return the D-Bus connection associated with this adaptor.
+ *
+ * \return The D-Bus connection associated with this adaptor.
+ */
 QDBusConnection AbstractAdaptor::dbusConnection() const
 {
     return mPriv->dbusConnection;
 }
 
+/**
+ * Return the adaptee object, i.e. the object that provides the implementation
+ * of this adaptor.
+ *
+ * \return The adaptee object.
+ */
 QObject *AbstractAdaptor::adaptee() const
 {
     return mPriv->adaptee;
diff --git a/TelepathyQt/base-connection-manager.cpp b/TelepathyQt/base-connection-manager.cpp
index 122b608c..7b09136f 100644
--- a/TelepathyQt/base-connection-manager.cpp
+++ b/TelepathyQt/base-connection-manager.cpp
@@ -166,6 +166,21 @@ void BaseConnectionManager::Adaptee::requestConnection(const QString &protocolNa
     context->setFinished(connection->busName(), QDBusObjectPath(connection->objectPath()));
 }
 
+/**
+ * \class BaseConnectionManager
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-connection-manager.h <TelepathyQt/BaseConnectionManager>
+ *
+ * \brief Base class for connection manager implementations.
+ */
+
+/**
+ * Constructs a new BaseConnectionManager object that implements a connection manager
+ * on the given \a dbusConnection and has the given \a name.
+ *
+ * \param dbusConnection The QDBusConnection to use.
+ * \param name The name of the connection manager.
+ */
 BaseConnectionManager::BaseConnectionManager(const QDBusConnection &dbusConnection,
         const QString &name)
     : DBusService(dbusConnection),
@@ -173,16 +188,32 @@ BaseConnectionManager::BaseConnectionManager(const QDBusConnection &dbusConnecti
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseConnectionManager::~BaseConnectionManager()
 {
     delete mPriv;
 }
 
+/**
+ * Return the connection manager's name, as given on the constructor.
+ *
+ * \return The connection manager's name.
+ */
 QString BaseConnectionManager::name() const
 {
     return mPriv->name;
 }
 
+/**
+ * Return the immutable properties of this connection manager object.
+ *
+ * Immutable properties cannot change after the object has been registered
+ * on the bus with registerObject().
+ *
+ * \return The immutable properties of this connection manager object.
+ */
 QVariantMap BaseConnectionManager::immutableProperties() const
 {
     QVariantMap ret;
@@ -190,21 +221,62 @@ QVariantMap BaseConnectionManager::immutableProperties() const
     return ret;
 }
 
+/**
+ * Return a list of all protocols that this connection manager implements.
+ *
+ * This property is immutable and cannot change after the connection manager
+ * has been registered on the bus with registerObject().
+ *
+ * \return A list of all protocols that this connection manager implements.
+ * \sa addProtocol(), hasProtocol(), protocol()
+ */
 QList<BaseProtocolPtr> BaseConnectionManager::protocols() const
 {
     return mPriv->protocols.values();
 }
 
+/**
+ * Return a pointer to the BaseProtocol instance that implements the protocol
+ * with the given \a protocolName, or a null BaseProtocolPtr if no such
+ * protocol has been added to the connection manager.
+ *
+ * \param protocolName The name of the protocol in interest.
+ * \return The BaseProtocol instance that implements the protocol with
+ * the given \a protocolName.
+ * \sa hasProtocol(), protocols(), addProtocol()
+ */
 BaseProtocolPtr BaseConnectionManager::protocol(const QString &protocolName) const
 {
     return mPriv->protocols.value(protocolName);
 }
 
+/**
+ * Return whether a protocol with the given \a protocolName has been
+ * added to the connection manager.
+ *
+ * \param protocolName The name of the protocol in interest.
+ * \return \c true if a protocol with the given \a protocolName has been
+ * added to the connection manager, or \c false otherwise.
+ * \sa addProtocol(), protocol(), protocols()
+ */
 bool BaseConnectionManager::hasProtocol(const QString &protocolName) const
 {
     return mPriv->protocols.contains(protocolName);
 }
 
+/**
+ * Add a new \a protocol to the list of protocols that this connection
+ * manager implements.
+ *
+ * Note that you cannot add new protocols after the connection manager
+ * has been registered on the bus with registerObject(). In addition,
+ * you cannot add two protocols with the same name. If any of these
+ * conditions is not met, this function will return false and print
+ * a suitable warning.
+ *
+ * \param protocol The protocol to add.
+ * \return \c true on success or \c false otherwise.
+ */
 bool BaseConnectionManager::addProtocol(const BaseProtocolPtr &protocol)
 {
     if (isRegistered()) {
@@ -236,6 +308,22 @@ bool BaseConnectionManager::addProtocol(const BaseProtocolPtr &protocol)
     return true;
 }
 
+/**
+ * Register this connection manager on the bus.
+ *
+ * A connection manager can only be registered once, and it
+ * should be registered only after all the protocols it implements
+ * have been added with addProtocol().
+ *
+ * If \a error is passed, any D-Bus error that may occur will
+ * be stored there.
+ *
+ * \param error A pointer to an empty DBusError where any
+ * possible D-Bus error will be stored.
+ * \return \c true on success and \c false if there was an error
+ * or this connection manager is already registered.
+ * \sa isRegistered()
+ */
 bool BaseConnectionManager::registerObject(DBusError *error)
 {
     if (isRegistered()) {
@@ -254,6 +342,9 @@ bool BaseConnectionManager::registerObject(DBusError *error)
     return ret;
 }
 
+/**
+ * Reimplemented from DBusService.
+ */
 bool BaseConnectionManager::registerObject(const QString &busName, const QString &objectPath,
         DBusError *error)
 {
@@ -284,6 +375,11 @@ bool BaseConnectionManager::registerObject(const QString &busName, const QString
     return true;
 }
 
+/**
+ * Return a list of all connections that have currently been made.
+ *
+ * \return A list of all connections that have currently been made.
+ */
 QList<BaseConnectionPtr> BaseConnectionManager::connections() const
 {
     return mPriv->connections.toList();
@@ -308,4 +404,16 @@ void BaseConnectionManager::removeConnection()
     mPriv->connections.remove(connection);
 }
 
+/**
+ * \fn void newConnection(const BaseConnectionPtr &connection)
+ *
+ * Emitted when a new connection has been requested by a client and
+ * the connection object has been constructed.
+ *
+ * To handle the connection request before a connection has been created,
+ * use BaseProtocol::setCreateConnectionCallback().
+ *
+ * \param connection The newly created connection
+ */
+
 }
diff --git a/TelepathyQt/base-connection.cpp b/TelepathyQt/base-connection.cpp
index 87e9c10a..c3b93b20 100644
--- a/TelepathyQt/base-connection.cpp
+++ b/TelepathyQt/base-connection.cpp
@@ -71,6 +71,22 @@ BaseConnection::Adaptee::~Adaptee()
 {
 }
 
+/**
+ * \class BaseConnection
+ * \ingroup serviceconn
+ * \headerfile TelepathyQt/base-connection.h <TelepathyQt/BaseConnection>
+ *
+ * \brief Base class for Connection implementations.
+ */
+
+/**
+ * Construct a BaseConnection.
+ *
+ * \param dbusConnection The D-Bus connection that will be used by this object.
+ * \param cmName The name of the connection manager associated with this connection.
+ * \param protocolName The name of the protocol associated with this connection.
+ * \param parameters The parameters of this connection.
+ */
 BaseConnection::BaseConnection(const QDBusConnection &dbusConnection,
         const QString &cmName, const QString &protocolName,
         const QVariantMap &parameters)
@@ -79,37 +95,80 @@ BaseConnection::BaseConnection(const QDBusConnection &dbusConnection,
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseConnection::~BaseConnection()
 {
     delete mPriv;
 }
 
+/**
+ * Return the name of the connection manager associated with this connection.
+ *
+ * \return The name of the connection manager associated with this connection.
+ */
 QString BaseConnection::cmName() const
 {
     return mPriv->cmName;
 }
 
+/**
+ * Return the name of the protocol associated with this connection.
+ *
+ * \return The name of the protocol associated with this connection.
+ */
 QString BaseConnection::protocolName() const
 {
     return mPriv->protocolName;
 }
 
+/**
+ * Return the parameters of this connection.
+ *
+ * \return The parameters of this connection.
+ */
 QVariantMap BaseConnection::parameters() const
 {
     return mPriv->parameters;
 }
 
+/**
+ * Return the immutable properties of this connection object.
+ *
+ * Immutable properties cannot change after the object has been registered
+ * on the bus with registerObject().
+ *
+ * \return The immutable properties of this connection object.
+ */
 QVariantMap BaseConnection::immutableProperties() const
 {
     // FIXME
     return QVariantMap();
 }
 
+/**
+ * Return a unique name for this connection.
+ *
+ * \return A unique name for this connection.
+ */
 QString BaseConnection::uniqueName() const
 {
     return QString(QLatin1String("_%1")).arg((intptr_t) this, 0, 16);
 }
 
+/**
+ * Register this connection object on the bus.
+ *
+ * If \a error is passed, any D-Bus error that may occur will
+ * be stored there.
+ *
+ * \param error A pointer to an empty DBusError where any
+ * possible D-Bus error will be stored.
+ * \return \c true on success and \c false if there was an error
+ * or this connection object is already registered.
+ * \sa isRegistered()
+ */
 bool BaseConnection::registerObject(DBusError *error)
 {
     if (isRegistered()) {
@@ -140,10 +199,19 @@ bool BaseConnection::registerObject(DBusError *error)
     return ret;
 }
 
+/**
+ * Reimplemented from DBusService.
+ */
 bool BaseConnection::registerObject(const QString &busName,
         const QString &objectPath, DBusError *error)
 {
     return DBusService::registerObject(busName, objectPath, error);
 }
 
+/**
+ * \fn void BaseConnection::disconnected()
+ *
+ * Emitted when this connection has been disconnected.
+ */
+
 }
diff --git a/TelepathyQt/base-protocol.cpp b/TelepathyQt/base-protocol.cpp
index ae83c7e9..3e28a0a7 100644
--- a/TelepathyQt/base-protocol.cpp
+++ b/TelepathyQt/base-protocol.cpp
@@ -160,22 +160,62 @@ void BaseProtocol::Adaptee::normalizeContact(const QString &contactId,
     context->setFinished(normalizedContactId);
 }
 
+/**
+ * \class BaseProtocol
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-protocol.h <TelepathyQt/BaseProtocol>
+ *
+ * \brief Base class for protocol implementations.
+ *
+ * A Protocol is a D-Bus object that implements an IM protocol (for instance, jabber or msn).
+ * The BaseProtocol class provides an easy way to implement a Protocol D-Bus object,
+ * by providing the basic functionality itself and allowing you to extend it by setting
+ * the appropriate properties and callbacks.
+ *
+ * A BaseProtocol instance cannot be registered by itself on the bus. You should add it
+ * to a BaseConnectionManager instance using BaseConnectionManager::addProtocol(). When
+ * the BaseConnectionManager is registered on the bus, all the BaseProtocol instances
+ * will also be registered.
+ */
+
+/**
+ * Constructs a new BaseProtocol object.
+ *
+ * \param dbusConnection The D-Bus connection to use.
+ * \param name The name of this protocol.
+ */
 BaseProtocol::BaseProtocol(const QDBusConnection &dbusConnection, const QString &name)
     : DBusService(dbusConnection),
       mPriv(new Private(this, dbusConnection, name))
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseProtocol::~BaseProtocol()
 {
     delete mPriv;
 }
 
+/**
+ * Return the protocol's name, as given on the constructor.
+ *
+ * \return The protocol's name.
+ */
 QString BaseProtocol::name() const
 {
     return mPriv->name;
 }
 
+/**
+ * Return the immutable properties of this protocol object.
+ *
+ * Immutable properties cannot change after the object has been registered
+ * on the bus with registerObject().
+ *
+ * \return The immutable properties of this protocol object.
+ */
 QVariantMap BaseProtocol::immutableProperties() const
 {
     QVariantMap ret;
@@ -193,11 +233,36 @@ QVariantMap BaseProtocol::immutableProperties() const
     return ret;
 }
 
+/**
+ * Return the list of interface names that have been set with
+ * setConnectionInterfaces().
+ *
+ * This list is exposed as the ConnectionInterfaces property of
+ * this Protocol object on the bus and represents interface names
+ * that might be in the Interfaces property of a Connection to this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The list of interface names that have been set with
+ * setConnectionInterfaces().
+ * \sa setConnectionInterfaces()
+ */
 QStringList BaseProtocol::connectionInterfaces() const
 {
     return mPriv->connInterfaces;
 }
 
+/**
+ * Set the interface names that may appear on Connection objects of
+ * this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param connInterfaces The list of interface names to set.
+ * \sa connectionInterfaces()
+ */
 void BaseProtocol::setConnectionInterfaces(const QStringList &connInterfaces)
 {
     if (isRegistered()) {
@@ -208,11 +273,34 @@ void BaseProtocol::setConnectionInterfaces(const QStringList &connInterfaces)
     mPriv->connInterfaces = connInterfaces;
 }
 
+/**
+ * Return the list of parameters that have been set with setParameters().
+ *
+ * This list is exposed as the Parameters property of this Protocol object
+ * on the bus and represents the parameters which may be specified in the
+ * Parameters property of an Account for this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The list of parameters that have been set with setParameters().
+ * \sa setParameters()
+ */
 ProtocolParameterList BaseProtocol::parameters() const
 {
     return mPriv->parameters;
 }
 
+/**
+ * Set the parameters that may be specified in the Parameters property
+ * of an Account for this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param parameters The list of parameters to set.
+ * \sa parameters()
+ */
 void BaseProtocol::setParameters(const ProtocolParameterList &parameters)
 {
     if (isRegistered()) {
@@ -223,11 +311,36 @@ void BaseProtocol::setParameters(const ProtocolParameterList &parameters)
     mPriv->parameters = parameters;
 }
 
+/**
+ * Return the list of requestable channel classes that have been set
+ * with setRequestableChannelClasses().
+ *
+ * This list is exposed as the RequestableChannelClasses property of
+ * this Protocol object on the bus and represents the channel classes
+ * which might be requestable from a Connection to this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \returns The list of requestable channel classes that have been set
+ * with setRequestableChannelClasses()
+ * \sa setRequestableChannelClasses()
+ */
 RequestableChannelClassSpecList BaseProtocol::requestableChannelClasses() const
 {
     return mPriv->rccSpecs;
 }
 
+/**
+ * Set the channel classes which might be requestable from a Connection
+ * to this protocol.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param rccSpecs The list of requestable channel classes to set.
+ * \sa requestableChannelClasses()
+ */
 void BaseProtocol::setRequestableChannelClasses(const RequestableChannelClassSpecList &rccSpecs)
 {
     if (isRegistered()) {
@@ -238,11 +351,37 @@ void BaseProtocol::setRequestableChannelClasses(const RequestableChannelClassSpe
     mPriv->rccSpecs = rccSpecs;
 }
 
+/**
+ * Return the name of the vCard field that has been set with setVCardField().
+ *
+ * This is exposed as the VCardField property of this Protocol object on
+ * the bus and represents the name of the most common vCard field used for
+ * this protocol's contact identifiers, normalized to lower case.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The name of the vCard field that has been set with setVCardField().
+ * \sa setVCardField()
+ */
 QString BaseProtocol::vCardField() const
 {
     return mPriv->vCardField;
 }
 
+/**
+ * Set the name of the most common vCard field used for
+ * this protocol's contact identifiers, normalized to lower case.
+ *
+ * For example, this would be x-jabber for Jabber/XMPP
+ * (including Google Talk), or tel for the PSTN.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param vCardField The name of the vCard field to set.
+ * \sa vCardField()
+ */
 void BaseProtocol::setVCardField(const QString &vCardField)
 {
     if (isRegistered()) {
@@ -253,11 +392,38 @@ void BaseProtocol::setVCardField(const QString &vCardField)
     mPriv->vCardField = vCardField;
 }
 
+/**
+ * Return the name that has been set with setEnglishName().
+ *
+ * This is exposed as the EnglishName property of this Protocol object on
+ * the bus and represents the name of the protocol in a form suitable
+ * for display to users, such as "AIM" or "Yahoo!".
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The name that has been set with setEnglishName().
+ * \sa setEnglishName()
+ */
 QString BaseProtocol::englishName() const
 {
     return mPriv->englishName;
 }
 
+/**
+ * Set the name of the protocol in a form suitable for display to users,
+ * such as "AIM" or "Yahoo!".
+ *
+ * This string should be in the C (english) locale. Clients are expected
+ * to lookup a translation on their own translation catalogs and fall back
+ * to this name if they have no translation for it.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param englishName The name to set.
+ * \sa englishName()
+ */
 void BaseProtocol::setEnglishName(const QString &englishName)
 {
     if (isRegistered()) {
@@ -268,11 +434,34 @@ void BaseProtocol::setEnglishName(const QString &englishName)
     mPriv->englishName = englishName;
 }
 
+/**
+ * Return the icon name that has been set with setIconName().
+ *
+ * This is exposed as the Icon property of this Protocol object on
+ * the bus and represents the name of an icon in the system's icon
+ * theme suitable for this protocol, such as "im-msn".
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The icon name set with setIconName().
+ * \sa setIconName()
+ */
 QString BaseProtocol::iconName() const
 {
     return mPriv->iconName;
 }
 
+/**
+ * Set the name of an icon in the system's icon theme suitable
+ * for this protocol, such as "im-msn".
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param iconName The icon name to set.
+ * \sa iconName()
+ */
 void BaseProtocol::setIconName(const QString &iconName)
 {
     if (isRegistered()) {
@@ -283,11 +472,37 @@ void BaseProtocol::setIconName(const QString &iconName)
      mPriv->iconName = iconName;
 }
 
+/**
+ * Return the list of interfaces that have been set with setAuthenticationTypes().
+ *
+ * This is exposed as the AuthenticationTypes property of this Protocol object
+ * on the bus and represents a list of D-Bus interfaces which provide
+ * information as to what kind of authentication channels can possibly appear
+ * before the connection reaches the CONNECTED state.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return The list of authentication types that have been
+ * set with setAuthenticationTypes().
+ * \sa setAuthenticationTypes()
+ */
 QStringList BaseProtocol::authenticationTypes() const
 {
     return mPriv->authTypes;
 }
 
+/**
+ * Set a list of D-Bus interfaces which provide information as to
+ * what kind of authentication channels can possibly appear before
+ * the connection reaches the CONNECTED state.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param authenticationTypes The list of interfaces to set.
+ * \sa authenticationTypes()
+ */
 void BaseProtocol::setAuthenticationTypes(const QStringList &authenticationTypes)
 {
     if (isRegistered()) {
@@ -298,11 +513,30 @@ void BaseProtocol::setAuthenticationTypes(const QStringList &authenticationTypes
     mPriv->authTypes = authenticationTypes;
 }
 
+/**
+ * Set a callback that will be called to create a new connection, when this
+ * has been requested by a client.
+ *
+ * \param cb The callback to set.
+ * \sa createConnection()
+ */
 void BaseProtocol::setCreateConnectionCallback(const CreateConnectionCallback &cb)
 {
     mPriv->createConnectionCb = cb;
 }
 
+/**
+ * Create a new connection object by calling the callback that has been set
+ * with setCreateConnectionCallback().
+ *
+ * \param parameters The connection parameters.
+ * \param error A pointer to a DBusError instance where any possible error
+ * will be stored.
+ * \return A pointer to the new connection, or a null BaseConnectionPtr if
+ * no connection could be created, in which case \a error will contain an
+ * appropriate error.
+ * \sa setCreateConnectionCallback()
+ */
 BaseConnectionPtr BaseProtocol::createConnection(const QVariantMap &parameters, Tp::DBusError *error)
 {
     if (!mPriv->createConnectionCb.isValid()) {
@@ -312,11 +546,34 @@ BaseConnectionPtr BaseProtocol::createConnection(const QVariantMap &parameters,
     return mPriv->createConnectionCb(parameters, error);
 }
 
+/**
+ * Set a callback that will be called from a client to identify an account.
+ *
+ * This callback will be called when the IdentifyAccount method on the Protocol
+ * D-Bus object has been called.
+ *
+ * \param cb The callback to set.
+ * \sa identifyAccount()
+ */
 void BaseProtocol::setIdentifyAccountCallback(const IdentifyAccountCallback &cb)
 {
     mPriv->identifyAccountCb = cb;
 }
 
+/**
+ * Return a string which uniquely identifies the account to which
+ * the given parameters would connect, by calling the callback that
+ * has been set with setIdentifyAccountCallback().
+ *
+ * \param parameters The connection parameters, as they would
+ * be provided to createConnection().
+ * \param error A pointer to a DBusError instance where any possible error
+ * will be stored.
+ * \return A string which uniquely identifies the account to which
+ * the given parameters would connect, or an empty string if no callback
+ * to create this string has been set with setIdentifyAccountCallback().
+ * \sa setIdentifyAccountCallback()
+ */
 QString BaseProtocol::identifyAccount(const QVariantMap &parameters, Tp::DBusError *error)
 {
     if (!mPriv->identifyAccountCb.isValid()) {
@@ -326,11 +583,28 @@ QString BaseProtocol::identifyAccount(const QVariantMap &parameters, Tp::DBusErr
     return mPriv->identifyAccountCb(parameters, error);
 }
 
+/**
+ * Set a callback that will be called from a client to normalize a contact id.
+ *
+ * \param cb The callback to set.
+ * \sa normalizeContact()
+ */
 void BaseProtocol::setNormalizeContactCallback(const NormalizeContactCallback &cb)
 {
     mPriv->normalizeContactCb = cb;
 }
 
+/**
+ * Return a normalized version of the given \a contactId, by calling the callback
+ * that has been set with setNormalizeContactCallback().
+ *
+ * \param contactId The contact ID to normalize.
+ * \param error A pointer to a DBusError instance where any possible error
+ * will be stored.
+ * \return A normalized version of the given \a contactId, or an empty string
+ * if no callback to do the normalization has been set with setNormalizeContactCallback().
+ * \sa setNormalizeContactCallback()
+ */
 QString BaseProtocol::normalizeContact(const QString &contactId, Tp::DBusError *error)
 {
     if (!mPriv->normalizeContactCb.isValid()) {
@@ -340,11 +614,32 @@ QString BaseProtocol::normalizeContact(const QString &contactId, Tp::DBusError *
     return mPriv->normalizeContactCb(contactId, error);
 }
 
+/**
+ * Return a list of interfaces that have been plugged into this Protocol
+ * D-Bus object with plugInterface().
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \return A list containing all the Protocol interface implementation objects.
+ * \sa plugInterface()
+ */
 QList<AbstractProtocolInterfacePtr> BaseProtocol::interfaces() const
 {
     return mPriv->interfaces.values();
 }
 
+/**
+ * Plug a new interface into this Protocol D-Bus object.
+ *
+ * This property is immutable and cannot change after this Protocol
+ * object has been registered on the bus with registerObject().
+ *
+ * \param interface An AbstractProtocolInterface instance that implements
+ * the interface that is to be plugged.
+ * \return \c true on success or \c false otherwise
+ * \sa interfaces()
+ */
 bool BaseProtocol::plugInterface(const AbstractProtocolInterfacePtr &interface)
 {
     if (isRegistered()) {
@@ -370,6 +665,9 @@ bool BaseProtocol::plugInterface(const AbstractProtocolInterfacePtr &interface)
     return true;
 }
 
+/**
+ * Reimplemented from DBusService.
+ */
 bool BaseProtocol::registerObject(const QString &busName, const QString &objectPath,
         DBusError *error)
 {
@@ -387,6 +685,14 @@ bool BaseProtocol::registerObject(const QString &busName, const QString &objectP
     return DBusService::registerObject(busName, objectPath, error);
 }
 
+/**
+ * \class AbstractProtocolInterface
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-protocol.h <TelepathyQt/AbstractProtocolInterface>
+ *
+ * \brief Base class for all the Protocol object interface implementations.
+ */
+
 // AbstractProtocolInterface
 AbstractProtocolInterface::AbstractProtocolInterface(const QString &interfaceName)
     : AbstractDBusServiceInterface(interfaceName)
@@ -461,49 +767,133 @@ struct TP_QT_NO_EXPORT BaseProtocolAddressingInterface::Private
     NormalizeContactUriCallback normalizeContactUriCb;
 };
 
+/**
+ * \class BaseProtocolAddressingInterface
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-protocol.h <TelepathyQt/BaseProtocolAddressingInterface>
+ *
+ * \brief Base class for implementations of Protocol.Interface.Addressing
+ */
+
+/**
+ * Class constructor.
+ */
 BaseProtocolAddressingInterface::BaseProtocolAddressingInterface()
     : AbstractProtocolInterface(TP_QT_IFACE_PROTOCOL_INTERFACE_ADDRESSING),
       mPriv(new Private)
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseProtocolAddressingInterface::~BaseProtocolAddressingInterface()
 {
     delete mPriv;
 }
 
+/**
+ * Return the immutable properties of this interface.
+ *
+ * Immutable properties cannot change after the interface has been registered
+ * on a service on the bus with registerInterface().
+ *
+ * \return The immutable properties of this interface.
+ */
 QVariantMap BaseProtocolAddressingInterface::immutableProperties() const
 {
     // no immutable property
     return QVariantMap();
 }
 
+/**
+ * Return the list of addressable vCard fields that have been set with
+ * setAddressableVCardFields().
+ *
+ * This list is exposed as the AddressableVCardFields property of this
+ * interface on the bus and represents the vCard fields that can be used
+ * to request a contact for this protocol, normalized to lower case.
+ *
+ * \return The list of addressable VCard fields that have been set with
+ * setAddressableVCardFields().
+ * \sa setAddressableVCardFields()
+ */
 QStringList BaseProtocolAddressingInterface::addressableVCardFields() const
 {
     return mPriv->addressableVCardFields;
 }
 
+/**
+ * Set the list of vCard fields that can be used to request a contact for this protocol.
+ *
+ * All the field names should be normalized to lower case.
+ *
+ * \param vcardFields The list of vCard fields to set.
+ * \sa addressableVCardFields()
+ */
 void BaseProtocolAddressingInterface::setAddressableVCardFields(const QStringList &vcardFields)
 {
     mPriv->addressableVCardFields = vcardFields;
 }
 
+/**
+ * Return the list of URI schemes that have been set with
+ * setAddressableUriSchemes().
+ *
+ * This list is exposed as the AddressableURISchemes property of this interface
+ * on the bus and represents the URI schemes that are supported by this
+ * protocol, like "tel" or "sip".
+ *
+ * \return The list of addressable URI schemes that have been set with
+ * setAddressableUriSchemes().
+ * \sa setAddressableUriSchemes()
+ */
 QStringList BaseProtocolAddressingInterface::addressableUriSchemes() const
 {
     return mPriv->addressableUriSchemes;
 }
 
+/**
+ * Set the list of URI schemes that are supported by this protocol.
+ *
+ * \param uriSchemes The list of URI schemes to set.
+ * \sa addressableUriSchemes()
+ */
 void BaseProtocolAddressingInterface::setAddressableUriSchemes(const QStringList &uriSchemes)
 {
     mPriv->addressableUriSchemes = uriSchemes;
 }
 
+/**
+ * Set a callback that will be called from a client to normalize a given
+ * vCard address.
+ *
+ * This callback will be called when the NormalizeVCardAddress method
+ * on the Protocol.Interface.Addressing D-Bus interface has been called.
+ *
+ * \param cb The callback to set.
+ * \sa normalizeVCardAddress()
+ */
 void BaseProtocolAddressingInterface::setNormalizeVCardAddressCallback(
         const NormalizeVCardAddressCallback &cb)
 {
     mPriv->normalizeVCardAddressCb = cb;
 }
 
+/**
+ * Return a normalized version of the given \a vCardAddress, which corresponds
+ * to the given \a vCardField, by calling the callback that has been set
+ * with setNormalizeVCardAddressCallback().
+ *
+ * \param vCardField The vCard field of the address we are normalizing.
+ * \param vCardAddress The address to normalize, which is assumed to belong to a contact.
+ * \param error A pointer to a DBusError instance where any possible error
+ * will be stored.
+ * \return A normalized version of the given \a vCardAddress, or an empty
+ * string if no callback to do the normalization has been set with
+ * setNormalizeVCardAddressCallback().
+ * \sa setNormalizeVCardAddressCallback()
+ */
 QString BaseProtocolAddressingInterface::normalizeVCardAddress(const QString &vCardField,
         const QString &vCardAddress, DBusError *error)
 {
@@ -514,12 +904,32 @@ QString BaseProtocolAddressingInterface::normalizeVCardAddress(const QString &vC
     return mPriv->normalizeVCardAddressCb(vCardField, vCardAddress, error);
 }
 
+/**
+ * Set a callback that will be called from a client to normalize a given contact URI.
+ *
+ * This callback will be called when the NormalizeContactURI method
+ * on the Protocol.Interface.Addressing D-Bus interface has been called.
+ *
+ * \param cb The callback to set.
+ * \sa normalizeContactUri()
+ */
 void BaseProtocolAddressingInterface::setNormalizeContactUriCallback(
         const NormalizeContactUriCallback &cb)
 {
     mPriv->normalizeContactUriCb = cb;
 }
 
+/**
+ * Return a normalized version of the given contact URI, \a uri, by calling
+ * the callback that has been set with setNormalizeContactUriCallback().
+ *
+ * \param uri The contact URI to normalize.
+ * \param error A pointer to a DBusError instance where any possible error
+ * will be stored.
+ * \return A normalized version of the given \a uri, or an empty string if no
+ * callback to do the normalization has been set with setNormalizeContactUriCallback().
+ * \sa setNormalizeContactUriCallback()
+ */
 QString BaseProtocolAddressingInterface::normalizeContactUri(const QString &uri, DBusError *error)
 {
     if (!mPriv->normalizeContactUriCb.isValid()) {
@@ -600,17 +1010,39 @@ struct TP_QT_NO_EXPORT BaseProtocolAvatarsInterface::Private
     AvatarSpec avatarDetails;
 };
 
+/**
+ * \class BaseProtocolAvatarsInterface
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-protocol.h <TelepathyQt/BaseProtocolAvatarsInterface>
+ *
+ * \brief Base class for implementations of Protocol.Interface.Avatars
+ */
+
+/**
+ * Class constructor.
+ */
 BaseProtocolAvatarsInterface::BaseProtocolAvatarsInterface()
     : AbstractProtocolInterface(TP_QT_IFACE_PROTOCOL_INTERFACE_AVATARS),
       mPriv(new Private)
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseProtocolAvatarsInterface::~BaseProtocolAvatarsInterface()
 {
     delete mPriv;
 }
 
+/**
+ * Return the immutable properties of this interface.
+ *
+ * Immutable properties cannot change after the interface has been registered
+ * on a service on the bus with registerInterface().
+ *
+ * \return The immutable properties of this interface.
+ */
 QVariantMap BaseProtocolAvatarsInterface::immutableProperties() const
 {
     QVariantMap ret;
@@ -625,11 +1057,34 @@ QVariantMap BaseProtocolAvatarsInterface::immutableProperties() const
     return ret;
 }
 
+/**
+ * Return the AvatarSpec that has been set with setAvatarDetails().
+ *
+ * The contents of this AvatarSpec are exposed as the various properties
+ * of this interface on the bus and represent the expected values of the
+ * Connection.Interface.Avatars properties on connections of this protocol.
+ *
+ * This property is immutable and cannot change after this interface
+ * has been registered on an object on the bus with registerInterface().
+ *
+ * \return The AvatarSpec that has been set with setAvatarDetails().
+ * \sa setAvatarDetails()
+ */
 AvatarSpec BaseProtocolAvatarsInterface::avatarDetails() const
 {
     return mPriv->avatarDetails;
 }
 
+/**
+ * Set the avatar details that will be exposed on the properties of this
+ * interface on the bus.
+ *
+ * This property is immutable and cannot change after this interface
+ * has been registered on an object on the bus with registerInterface().
+ *
+ * \param details The details to set.
+ * \sa avatarDetails()
+ */
 void BaseProtocolAvatarsInterface::setAvatarDetails(const AvatarSpec &details)
 {
     if (isRegistered()) {
@@ -676,28 +1131,75 @@ struct TP_QT_NO_EXPORT BaseProtocolPresenceInterface::Private
     PresenceSpecList statuses;
 };
 
+/**
+ * \class BaseProtocolPresenceInterface
+ * \ingroup servicecm
+ * \headerfile TelepathyQt/base-protocol.h <TelepathyQt/BaseProtocolPresenceInterface>
+ *
+ * \brief Base class for implementations of Protocol.Interface.Presence
+ */
+
+/**
+ * Class constructor.
+ */
 BaseProtocolPresenceInterface::BaseProtocolPresenceInterface()
     : AbstractProtocolInterface(TP_QT_IFACE_PROTOCOL_INTERFACE_PRESENCE),
       mPriv(new Private)
 {
 }
 
+/**
+ * Class destructor.
+ */
 BaseProtocolPresenceInterface::~BaseProtocolPresenceInterface()
 {
     delete mPriv;
 }
 
+/**
+ * Return the immutable properties of this interface.
+ *
+ * Immutable properties cannot change after the interface has been registered
+ * on a service on the bus with registerInterface().
+ *
+ * \return The immutable properties of this interface.
+ */
 QVariantMap BaseProtocolPresenceInterface::immutableProperties() const
 {
     // no immutable property
     return QVariantMap();
 }
 
+/**
+ * Return the list of presence statuses that have been set with setStatuses().
+ *
+ * This list is exposed as the Statuses property of this interface on the bus
+ * and represents the statuses that might appear in the
+ * Connection.Interface.SimplePresence.Statuses property on a connection to
+ * this protocol that supports SimplePresence.
+ *
+ * This property is immutable and cannot change after this interface
+ * has been registered on an object on the bus with registerInterface().
+ *
+ * \return The list of presence statuses that have been set with setStatuses().
+ * \sa setStatuses()
+ */
 PresenceSpecList BaseProtocolPresenceInterface::statuses() const
 {
     return mPriv->statuses;
 }
 
+/**
+ * Set the list of statuses that might appear in the
+ * Connection.Interface.SimplePresence.Statuses property on a connection to
+ * this protocol that supports SimplePresence.
+ *
+ * This property is immutable and cannot change after this interface
+ * has been registered on an object on the bus with registerInterface().
+ *
+ * \param statuses The statuses list to set.
+ * \sa statuses()
+ */
 void BaseProtocolPresenceInterface::setStatuses(const PresenceSpecList &statuses)
 {
     if (isRegistered()) {
diff --git a/TelepathyQt/callbacks.dox b/TelepathyQt/callbacks.dox
new file mode 100644
index 00000000..688d7c8a
--- /dev/null
+++ b/TelepathyQt/callbacks.dox
@@ -0,0 +1,161 @@
+/*
+ * This file is part of TelepathyQt
+ *
+ * @copyright Copyright (C) 2012 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @copyright Copyright (C) 2012 Nokia Corporation
+ * @license LGPL 2.1
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+/**
+ * \page callbacks Callbacks Usage
+ *
+ * \section callbacks_overview Overview
+ *
+ * Callbacks are used in Telepathy-Qt by the service side high-level APIs
+ * to expose methods that may/should be overriden in implementations.
+ *
+ * Ideally we would use virtual methods for this, but as new methods
+ * can be added freely (when interfaces change), we would not be able
+ * to guarantee a stable API/ABI. Other options, such as virtual padding,
+ * virtual_hook and Qt slots also have their own drawbacks.
+ *
+ * There are 8 Callback classes, Tp::Callback0 to Tp::Callback7, which
+ * define a callback with 0 to 7 arguments respectively. The first template
+ * argument is always the return value type and the rest template arguments
+ * are the types of the callback arguments in the order that they are passed
+ * to the callback.
+ *
+ * Callback classes can be constructed from a functor. To make it easy to
+ * use function pointers as functors, Telepathy-Qt also provides two helper
+ * functions, Tp::memFun and Tp::ptrFun.
+ *
+ * Here is an example of their usage:
+ * \code
+ * // assuming a member function QString MyImpl::myFunc(const QString & s, int i);
+ * Tp::Callback2<QString, const QString &, int> cb = Tp::memFun(myObj, &MyImpl::myFunc);
+ *
+ * // assuming a non-member or static member function QString myFunc(const QString & s, int i);
+ * Tp::Callback2<QString, const QString &, int> cb = Tp::ptrFun(&myFunc);
+ *
+ * // assuming Tp::BaseConnectionPtr MyProtocolImpl::createConnection(const QVariantMap &parameters, DBusError *error);
+ * myBaseProtocol->setCreateConnectionCallback(Tp::memFun(myProtocolImpl, &MyProtocolImpl::createConnection));
+ * \endcode
+ *
+ * You are also free to use any other mechanism for constructing functors,
+ * such as boost::bind, C++11's <functional> module or even C++11 lambda functions.
+ */
+
+/**
+ * \class Tp::BaseCallback
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Base class for all the callback classes
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \fn bool Tp::BaseCallback::isValid() const
+ *
+ * Return whether this callback object has a valid functor assigned to it
+ * or if it's a default-constructed dummy callback object.
+ *
+ * \return \c false if this is a default-constructed callback or
+ * \c true if this callback was constructed from a functor.
+ */
+
+/**
+ * \class Tp::Callback0
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 0 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback1
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 1 argument
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback2
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 2 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback3
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 3 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback4
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 4 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback5
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 5 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback6
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 6 arguments
+ *
+ * See \ref callbacks
+ */
+
+/**
+ * \class Tp::Callback7
+ * \ingroup utils
+ * \headerfile TelepathyQt/callbacks.h <TelepathyQt/Callbacks>
+ *
+ * \brief Callback with 7 arguments
+ *
+ * See \ref callbacks
+ */
+
diff --git a/TelepathyQt/dbus-error.cpp b/TelepathyQt/dbus-error.cpp
index 4c99bed6..c4768789 100644
--- a/TelepathyQt/dbus-error.cpp
+++ b/TelepathyQt/dbus-error.cpp
@@ -39,20 +39,47 @@ struct TP_QT_NO_EXPORT DBusError::Private
     QString message;
 };
 
+/**
+ * \class DBusError
+ * \ingroup servicesideimpl
+ * \headerfile TelepathyQt/dbus-error.h <TelepathyQt/DBusError>
+ *
+ * \brief Small container class, containing a D-Bus error
+ */
+
+/**
+ * Construct an empty DBusError
+ */
 DBusError::DBusError()
     : mPriv(0)
 {
 }
 
+/**
+ * Construct a DBusError with the given error \a name and \a message.
+ *
+ * \param name The D-Bus error name.
+ * \param message A human-readable description of the error.
+ */
 DBusError::DBusError(const QString &name, const QString &message)
     : mPriv(new Private(name, message))
 {
 }
 
+/**
+ * Class destructor.
+ */
 DBusError::~DBusError()
 {
 }
 
+/**
+ * Compare this error with another one.
+ *
+ * \param other The other error to compare to.
+ * \return \c true if the two errors have the same name and message
+ * or \c false otherwise.
+ */
 bool DBusError::operator==(const DBusError &other) const
 {
     if (!isValid() || !other.isValid()) {
@@ -66,6 +93,13 @@ bool DBusError::operator==(const DBusError &other) const
         mPriv->message == other.mPriv->message;
 }
 
+/**
+ * Compare this error with another one.
+ *
+ * \param other The other error to compare to.
+ * \return \c false if the two errors have the same name and message
+ * or \c true otherwise.
+ */
 bool DBusError::operator!=(const DBusError &other) const
 {
     if (!isValid() || !other.isValid()) {
@@ -79,6 +113,11 @@ bool DBusError::operator!=(const DBusError &other) const
         mPriv->message != other.mPriv->message;
 }
 
+/**
+ * Return the D-Bus name of this error.
+ *
+ * \return The D-Bus name of this error.
+ */
 QString DBusError::name() const
 {
     if (!isValid()) {
@@ -88,6 +127,11 @@ QString DBusError::name() const
     return mPriv->name;
 }
 
+/**
+ * Return the human-readable description of the error.
+ *
+ * \return The human-readable description of the error.
+ */
 QString DBusError::message() const
 {
     if (!isValid()) {
@@ -97,6 +141,12 @@ QString DBusError::message() const
     return mPriv->message;
 }
 
+/**
+ * Set this DBusError to contain the given error \a name and \a message.
+ *
+ * \param name The D-Bus error name to set.
+ * \param message The description of the error to set.
+ */
 void DBusError::set(const QString &name, const QString &message)
 {
     if (!isValid()) {
@@ -108,4 +158,13 @@ void DBusError::set(const QString &name, const QString &message)
     mPriv->message = message;
 }
 
+/**
+ * \fn bool DBusError::isValid() const
+ *
+ * Return whether this DBusError is set to contain an error or not.
+ *
+ * \return \c true if the error name and message have been set,
+ * or \c false otherwise.
+ */
+
 } // Tp
diff --git a/TelepathyQt/dbus-object.cpp b/TelepathyQt/dbus-object.cpp
index 8cd2dc72..9a311d3e 100644
--- a/TelepathyQt/dbus-object.cpp
+++ b/TelepathyQt/dbus-object.cpp
@@ -37,17 +37,40 @@ struct TP_QT_NO_EXPORT DBusObject::Private
     QDBusConnection dbusConnection;
 };
 
+/**
+ * \class DBusObject
+ * \ingroup servicesideimpl
+ * \headerfile TelepathyQt/dbus-object.h <TelepathyQt/DBusObject>
+ *
+ * \brief A QObject on which low-level D-Bus adaptors are plugged to provide a D-Bus object.
+ */
+
+
+/**
+ * Construct a DBusObject that operates on the given \a dbusConnection.
+ *
+ * \param dbusConnection The D-Bus connection to use.
+ * \param parent The QObject parent of this instance.
+ */
 DBusObject::DBusObject(const QDBusConnection &dbusConnection, QObject *parent)
     : QObject(parent),
       mPriv(new Private(dbusConnection))
 {
 }
 
+/**
+ * Class destructor.
+ */
 DBusObject::~DBusObject()
 {
     delete mPriv;
 }
 
+/**
+ * Return the D-Bus connection associated with this object.
+ *
+ * \return The D-Bus connection associated with this object.
+ */
 QDBusConnection DBusObject::dbusConnection() const
 {
     return mPriv->dbusConnection;
diff --git a/TelepathyQt/dbus-service.cpp b/TelepathyQt/dbus-service.cpp
index 769ac511..a22c6569 100644
--- a/TelepathyQt/dbus-service.cpp
+++ b/TelepathyQt/dbus-service.cpp
@@ -51,41 +51,113 @@ struct TP_QT_NO_EXPORT DBusService::Private
     bool registered;
 };
 
+/**
+ * \class DBusService
+ * \ingroup servicesideimpl
+ * \headerfile TelepathyQt/dbus-service.h <TelepathyQt/DBusService>
+ *
+ * \brief Base class for D-Bus services.
+ *
+ * This class serves as a base for all the classes that are used to implement
+ * D-Bus services.
+ */
+
+/**
+ * Construct a DBusService that uses the given \a dbusConnection.
+ *
+ * \param dbusConnection The D-Bus connection that will be used by this service.
+ */
 DBusService::DBusService(const QDBusConnection &dbusConnection)
     : mPriv(new Private(this, dbusConnection))
 {
 }
 
+/**
+ * Class destructor.
+ */
 DBusService::~DBusService()
 {
     delete mPriv;
 }
 
+/**
+ * Return the D-Bus connection associated with this service.
+ *
+ * \return the D-Bus connection associated with this service.
+ */
 QDBusConnection DBusService::dbusConnection() const
 {
     return mPriv->dbusObject->dbusConnection();
 }
 
+/**
+ * Return the D-Bus service name of this service.
+ *
+ * This is only valid after this service has been registered
+ * on the bus using registerObject().
+ *
+ * \return the D-Bus service name of this service.
+ */
 QString DBusService::busName() const
 {
     return mPriv->busName;
 }
 
+/**
+ * Return the D-Bus object path of this service.
+ *
+ * This is only valid after this service has been registered
+ * on the bus using registerObject().
+ *
+ * \return the D-Bus object path of this service.
+ */
 QString DBusService::objectPath() const
 {
     return mPriv->objectPath;
 }
 
+/**
+ * Return the DBusObject that is used for registering this service on the bus.
+ *
+ * The DBusObject is the object on which all the interface adaptors
+ * for this service are plugged.
+ *
+ * \return a pointer to the DBusObject that is used for registering
+ * this service on the bus.
+ */
 DBusObject *DBusService::dbusObject() const
 {
     return mPriv->dbusObject;
 }
 
+/**
+ * Return whether this D-Bus service has been registered on the bus or not.
+ *
+ * \return \c true if the service has been registered, or \c false otherwise.
+ */
 bool DBusService::isRegistered() const
 {
     return mPriv->registered;
 }
 
+/**
+ * Register this service object on the bus with the given \a busName and \a objectPath.
+ *
+ * \a error needs to be a valid pointer to a DBusError instance, where any
+ * possible D-Bus error will be stored.
+ *
+ * A service may only be registered once in its lifetime.
+ * Use isRegistered() to find out if it has already been registered or not.
+ *
+ * You normally don't need to use this method directly.
+ * Subclasses should provide a simplified version of it.
+ *
+ * \param busName The D-Bus service name of this object.
+ * \param objectPath The D-Bus object path of this object.
+ * \param error A pointer to a valid DBusError instance, where any
+ * possible D-Bus error will be stored.
+ * \return \c true on success or \c false otherwise.
+ */
 bool DBusService::registerObject(const QString &busName, const QString &objectPath,
         DBusError *error)
 {
@@ -119,6 +191,17 @@ bool DBusService::registerObject(const QString &busName, const QString &objectPa
     return true;
 }
 
+/**
+ * \fn QVariantMap DBusService::immutableProperties() const
+ *
+ * Return the immutable properties of this D-Bus service object.
+ *
+ * Immutable properties cannot change after the object has been registered
+ * on the bus with registerObject().
+ *
+ * \return The immutable properties of this D-Bus service object.
+ */
+
 struct AbstractDBusServiceInterface::Private
 {
     Private(const QString &interfaceName)
@@ -133,31 +216,82 @@ struct AbstractDBusServiceInterface::Private
     bool registered;
 };
 
+/**
+ * \class AbstractDBusServiceInterface
+ * \ingroup servicesideimpl
+ * \headerfile TelepathyQt/dbus-service.h <TelepathyQt/AbstractDBusServiceInterface>
+ *
+ * \brief Base class for D-Bus service interfaces.
+ *
+ * This class serves as a base for all the classes that are used to implement
+ * interfaces that sit on top of D-Bus services.
+ */
+
+/**
+ * Construct an AbstractDBusServiceInterface that implements
+ * the interface with the given \a interfaceName.
+ *
+ * \param interfaceName The name of the interface that this class implements.
+ */
 AbstractDBusServiceInterface::AbstractDBusServiceInterface(const QString &interfaceName)
     : mPriv(new Private(interfaceName))
 {
 }
 
+/**
+ * Class destructor.
+ */
 AbstractDBusServiceInterface::~AbstractDBusServiceInterface()
 {
     delete mPriv;
 }
 
+/**
+ * Return the name of the interface that this class implements,
+ * as given on the constructor.
+ *
+ * \return The name of the interface that this class implements.
+ */
 QString AbstractDBusServiceInterface::interfaceName() const
 {
     return mPriv->interfaceName;
 }
 
+/**
+ * Return the DBusObject on which the adaptor of this interface is plugged.
+ *
+ * This is only accessible after the interface has been registered
+ * with registerInterface().
+ *
+ * \return a pointer to the DBusObject on which the adaptor
+ * of this interface is plugged.
+ * \sa DBusService::dbusObject()
+ */
 DBusObject *AbstractDBusServiceInterface::dbusObject() const
 {
     return mPriv->dbusObject;
 }
 
+/**
+ * Return whether this interface has been registered.
+ *
+ * \return \c true if the service has been registered, or \c false otherwise.
+ * \sa registerInterface()
+ */
 bool AbstractDBusServiceInterface::isRegistered() const
 {
     return mPriv->registered;
 }
 
+/**
+ * Registers this interface by plugging its adaptor
+ * on the given \a dbusObject.
+ *
+ * \param dbusObject The object on which to plug the adaptor.
+ * \return \c false if the interface has already been registered,
+ * or \a true otherwise.
+ * \sa isRegistered()
+ */
 bool AbstractDBusServiceInterface::registerInterface(DBusObject *dbusObject)
 {
     if (mPriv->registered) {
@@ -170,4 +304,23 @@ bool AbstractDBusServiceInterface::registerInterface(DBusObject *dbusObject)
     return true;
 }
 
+/**
+ * \fn QVariantMap AbstractDBusServiceInterface::immutableProperties() const
+ *
+ * Return the immutable properties of this interface.
+ *
+ * Immutable properties cannot change after the interface has been registered
+ * on a service on the bus with registerInterface().
+ *
+ * \return The immutable properties of this interface.
+ */
+
+/**
+ * \fn void AbstractDBusServiceInterface::createAdaptor()
+ *
+ * Create the adaptor for this interface.
+ *
+ * Subclasses should reimplement this appropriately.
+ */
+
 }
diff --git a/TelepathyQt/groups.dox b/TelepathyQt/groups.dox
index bf7d34b3..a5415c4d 100644
--- a/TelepathyQt/groups.dox
+++ b/TelepathyQt/groups.dox
@@ -103,6 +103,36 @@
  */
 
 /**
+ * \defgroup servicesideimpl Service-side implementation
+ *
+ * Classes to implement service D-Bus objects.
+ */
+
+/**
+ * \defgroup servicechannel Channel service implementation
+ * \ingroup servicesideimpl
+ *
+ * Classes to implement Telepathy Channel objects and their
+ * optional interfaces.
+ */
+
+/**
+ * \defgroup servicecm Connection manager service implementation
+ * \ingroup servicesideimpl
+ *
+ * Classes to implement Telepathy ConnectionManager objects and their
+ * optional interfaces.
+ */
+
+/**
+ * \defgroup serviceconn Connection service implementation
+ * \ingroup servicesideimpl
+ *
+ * Classes to implement Telepathy Connection objects and their
+ * optional interfaces.
+ */
+
+/**
  * \defgroup wrappers Wrapper classes
  *
  * Wrapper classes representing a Telepathy type.