[Telepathy-commits] [telepathy-qt4/master] Moved ConnectionManager docs to source file and added more docs.
Andre Moreira Magalhaes (andrunko)
andre.magalhaes at collabora.co.uk
Tue Jan 6 12:52:16 PST 2009
---
TelepathyQt4/Client/connection-manager.cpp | 175 +++++++++++++++++++++++++++-
TelepathyQt4/Client/connection-manager.h | 96 ---------------
2 files changed, 172 insertions(+), 99 deletions(-)
diff --git a/TelepathyQt4/Client/connection-manager.cpp b/TelepathyQt4/Client/connection-manager.cpp
index 40a98e4..5506d6f 100644
--- a/TelepathyQt4/Client/connection-manager.cpp
+++ b/TelepathyQt4/Client/connection-manager.cpp
@@ -40,6 +40,24 @@
#include <QStringList>
#include <QTimer>
+/**
+ * \addtogroup clientsideproxies Client-side proxies
+ *
+ * Proxy objects representing remote service objects accessed via D-Bus.
+ *
+ * In addition to providing direct access to methods, signals and properties
+ * exported by the remote objects, some of these proxies offer features like
+ * automatic inspection of remote object capabilities, property tracking,
+ * backwards compatibility helpers for older services and other utilities.
+ */
+
+/**
+ * \defgroup clientcm Connection manager proxies
+ * \ingroup clientsideproxies
+ *
+ * Proxy objects representing remote Telepathy ConnectionManager objects.
+ */
+
namespace Telepathy
{
namespace Client
@@ -92,6 +110,16 @@ struct ProtocolInfo::Private
ProtocolParameterList params;
};
+/**
+ * \class ProtocolInfo
+ * \ingroup clientcm
+ * \headerfile TelepathyQt4/Client/connection-manager.h <TelepathyQt4/Client/ConnectionManager>
+ *
+ * Object representing a Telepathy protocol info.
+ *
+ * \param cmName Name of the connection manager
+ * \param name Name of the protocol
+ */
ProtocolInfo::ProtocolInfo(const QString &cmName, const QString &name)
: mPriv(new Private()),
mCmName(cmName),
@@ -99,6 +127,9 @@ ProtocolInfo::ProtocolInfo(const QString &cmName, const QString &name)
{
}
+/**
+ * Class destructor.
+ */
ProtocolInfo::~ProtocolInfo()
{
Q_FOREACH (ProtocolParameter *param, mPriv->params) {
@@ -106,11 +137,46 @@ ProtocolInfo::~ProtocolInfo()
}
}
+/**
+ * \fn QString ProtocolInfo::cmName() const
+ *
+ * Get the short name of the connection manager (e.g. "gabble").
+ *
+ * \return The name of the connection manager
+ */
+
+/**
+ * \fn QString ProtocolInfo::name() const
+ *
+ * Get the string identifying the protocol as described in the Telepathy
+ * D-Bus API Specification (e.g. "jabber").
+ *
+ * This identifier is not intended to be displayed to users directly; user
+ * interfaces are responsible for mapping them to localized strings.
+ *
+ * \return A string identifying the protocol
+ */
+
+/**
+ * Return all supported parameters. The parameters' names
+ * may either be the well-known strings specified by the Telepathy D-Bus
+ * API Specification (e.g. "account" and "password"), or
+ * implementation-specific strings.
+ *
+ * \return A list of parameters
+ */
const ProtocolParameterList &ProtocolInfo::parameters() const
{
return mPriv->params;
}
+/**
+ * Return whether a given parameter can be passed to the connection
+ * manager when creating a connection to this protocol.
+ *
+ * \param name The name of a parameter
+ * \return true if the given parameter exists
+ */
bool ProtocolInfo::hasParameter(const QString &name) const
{
Q_FOREACH (ProtocolParameter *param, mPriv->params) {
@@ -121,6 +187,14 @@ bool ProtocolInfo::hasParameter(const QString &name) const
return false;
}
+/**
+ * Return whether it might be possible to register new accounts on this
+ * protocol via Telepathy, by setting the special parameter named
+ * <code>register</code> to <code>true</code>.
+ *
+ * \return The same thing as hasParameter("register")
+ * \sa hasParameter()
+ */
bool ProtocolInfo::canRegister() const
{
return hasParameter(QLatin1String("register"));
@@ -421,7 +495,21 @@ void ConnectionManager::Private::continueIntrospection()
}
}
-
+/**
+ * \class ConnectionManager
+ * \ingroup clientcm
+ * \headerfile TelepathyQt4/Client/connection-manager.h <TelepathyQt4/Client/ConnectionManager>
+ *
+ * Object representing a Telepathy connection manager. Connection managers
+ * allow connections to be made on one or more protocols.
+ *
+ * Most client applications should use this functionality via the
+ * %AccountManager, to allow connections to be shared between client
+ * applications.
+ *
+ * \param name Name of the connection manager
+ * \param parent Object parent
+ */
ConnectionManager::ConnectionManager(const QString &name, QObject *parent)
: StatelessDBusProxy(QDBusConnection::sessionBus(),
Private::makeBusName(name), Private::makeObjectPath(name),
@@ -430,6 +518,22 @@ ConnectionManager::ConnectionManager(const QString &name, QObject *parent)
{
}
+/**
+ * \class ConnectionManager
+ * \ingroup clientcm
+ * \headerfile TelepathyQt4/Client/connection-manager.h <TelepathyQt4/Client/ConnectionManager>
+ *
+ * Object representing a Telepathy connection manager. Connection managers
+ * allow connections to be made on one or more protocols.
+ *
+ * Most client applications should use this functionality via the
+ * %AccountManager, to allow connections to be shared between client
+ * applications.
+ *
+ * \param bus QDBusConnection to use
+ * \param name Name of the connection manager
+ * \param parent Object parent
+ */
ConnectionManager::ConnectionManager(const QDBusConnection &bus,
const QString &name, QObject *parent)
: StatelessDBusProxy(bus, Private::makeBusName(name),
@@ -438,11 +542,19 @@ ConnectionManager::ConnectionManager(const QDBusConnection &bus,
{
}
+/**
+ * Class destructor.
+ */
ConnectionManager::~ConnectionManager()
{
delete mPriv;
}
+/**
+ * Get the short name of the connection manager (e.g. "gabble").
+ *
+ * \return The name of the connection manager
+ */
QString ConnectionManager::name() const
{
return mPriv->name;
@@ -453,6 +565,16 @@ QStringList ConnectionManager::interfaces() const
return mPriv->interfaces;
}
+/**
+ * Get a list of strings identifying the protocols supported by this
+ * connection manager, as described in the Telepathy
+ * D-Bus API Specification (e.g. "jabber").
+ *
+ * These identifiers are not intended to be displayed to users directly; user
+ * interfaces are responsible for mapping them to localized strings.
+ *
+ * \return A list of supported protocols
+ */
QStringList ConnectionManager::supportedProtocols() const
{
QStringList protocols;
@@ -462,18 +584,47 @@ QStringList ConnectionManager::supportedProtocols() const
return protocols;
}
+/**
+ * Get a list of protocols info for this connection manager.
+ *
+ * \return A list of á¹”rotocolInfo
+ */
const ProtocolInfoList &ConnectionManager::protocols() const
{
return mPriv->protocols;
}
+/**
+ * \fn DBus::propertiesInterface *ConnectionManager::propertiesInterface() const
+ *
+ * Convenience function for getting a Properties interface proxy. The
+ * Properties interface is not necessarily reported by the services, so a
+ * <code>check</code> parameter is not provided, and the interface is
+ * always assumed to be present.
+ */
+
+/**
+ * Return whether this object has finished its initial setup.
+ *
+ * This is mostly useful as a sanity check, in code that shouldn't be run
+ * until the object is ready. To wait for the object to be ready, call
+ * becomeReady() and connect to the finished signal on the result.
+ *
+ * \return \c true if the object has finished initial setup
+ */
bool ConnectionManager::isReady() const
{
return mPriv->ready;
}
-// TODO: We don't actually consider anything during initial setup to be
-// fatal, so the documentation isn't completely true.
+/**
+ * Return a pending operation which will succeed when this object finishes
+ * its initial setup, or will fail if a fatal error occurs during this
+ * initial setup.
+ *
+ * \return A PendingOperation which will emit PendingOperation::finished
+ * when this object has finished or failed its initial setup
+ */
PendingOperation *ConnectionManager::becomeReady()
{
if (mPriv->ready) {
@@ -487,11 +638,29 @@ PendingOperation *ConnectionManager::becomeReady()
return mPriv->pendingReady;
}
+/**
+ * Returns a pending operation from which a list of all installed connection
+ * manager short names (such as "gabble" or "haze") can be retrieved if it
+ * succeeds.
+ *
+ * \return A PendingStringList which will emit PendingStringList::finished
+ * when this object has finished or failed getting the connection
+ * manager names.
+ */
PendingStringList *ConnectionManager::listNames(const QDBusConnection &bus)
{
return new ConnectionManager::Private::PendingNames(bus);
}
+/**
+ * Get the ConnectionManagerInterface for this ConnectionManager. This
+ * method is protected since the convenience methods provided by this
+ * class should generally be used instead of calling D-Bus methods
+ * directly.
+ *
+ * \return A pointer to the existing ConnectionManagerInterface for this
+ * ConnectionManager
+ */
ConnectionManagerInterface *ConnectionManager::baseInterface() const
{
return mPriv->baseInterface;
diff --git a/TelepathyQt4/Client/connection-manager.h b/TelepathyQt4/Client/connection-manager.h
index 4823c61..b4e33a4 100644
--- a/TelepathyQt4/Client/connection-manager.h
+++ b/TelepathyQt4/Client/connection-manager.h
@@ -26,24 +26,6 @@
#error IN_TELEPATHY_QT4_HEADER
#endif
-/**
- * \addtogroup clientsideproxies Client-side proxies
- *
- * Proxy objects representing remote service objects accessed via D-Bus.
- *
- * In addition to providing direct access to methods, signals and properties
- * exported by the remote objects, some of these proxies offer features like
- * automatic inspection of remote object capabilities, property tracking,
- * backwards compatibility helpers for older services and other utilities.
- */
-
-/**
- * \defgroup clientcm Connection manager proxies
- * \ingroup clientsideproxies
- *
- * Proxy objects representing remote Telepathy ConnectionManager objects.
- */
-
#include <TelepathyQt4/_gen/cli-connection-manager.h>
#include <TelepathyQt4/Client/DBus>
@@ -104,45 +86,13 @@ class ProtocolInfo
public:
~ProtocolInfo();
- /**
- * Get the short name of the connection manager (e.g. "gabble").
- *
- * \return The name of the connection manager
- */
QString cmName() const { return mCmName; }
- /**
- * Get the untranslated name of the protocol as described in the Telepathy
- * D-Bus API Specification (e.g. "jabber").
- */
QString name() const { return mName; }
- /**
- * Return all supported parameters. The parameters' names
- * may either be the well-known strings specified by the Telepathy D-Bus
- * API Specification (e.g. "account" and "password"), or
- * implementation-specific strings.
- *
- * \return A list of parameters
- */
const ProtocolParameterList ¶meters() const;
-
- /**
- * Return whether a given parameter can be passed to the connection
- * manager when creating a connection to this protocol.
- *
- * \param name The name of a parameter
- * \return true if the given parameter exists
- */
bool hasParameter(const QString &name) const;
- /**
- * Return whether it might be possible to register new accounts on this
- * protocol via Telepathy, by setting the special parameter named
- * <code>register</code> to <code>true</code>.
- *
- * \return The same thing as hasParameter("register")
- */
bool canRegister() const;
private:
@@ -161,18 +111,6 @@ private:
};
-/**
- * \class ConnectionManager
- * \ingroup clientcm
- * \headerfile TelepathyQt4/Client/connection-manager.h <TelepathyQt4/Client/ConnectionManager>
- *
- * Object representing a Telepathy connection manager. Connection managers
- * allow connections to be made on one or more protocols.
- *
- * Most client applications should use this functionality via the
- * %AccountManager, to allow connections to be shared between client
- * applications.
- */
class ConnectionManager : public StatelessDBusProxy,
private OptionalInterfaceFactory
{
@@ -190,55 +128,21 @@ public:
QStringList interfaces() const;
QStringList supportedProtocols() const;
-
const ProtocolInfoList &protocols() const;
- /**
- * Convenience function for getting a Properties interface proxy. The
- * Properties interface is not necessarily reported by the services, so a
- * <code>check</code> parameter is not provided, and the interface is
- * always assumed to be present.
- */
inline DBus::PropertiesInterface *propertiesInterface() const
{
return OptionalInterfaceFactory::interface<DBus::PropertiesInterface>(
*baseInterface());
}
- /**
- * Return whether this object has finished its initial setup.
- *
- * This is mostly useful as a sanity check, in code that shouldn't be run
- * until the object is ready. To wait for the object to be ready, call
- * becomeReady() and connect to the finished signal on the result.
- *
- * \return \c true if the object has finished initial setup
- */
bool isReady() const;
- // FIXME: a better name for this would be nice
- /**
- * Return a pending operation which will succeed when this object finishes
- * its initial setup, or will fail if a fatal error occurs during this
- * initial setup.
- *
- * \return A PendingOperation which will emit PendingOperation::finished
- * when this object has finished or failed its initial setup
- */
PendingOperation *becomeReady();
static PendingStringList *listNames(const QDBusConnection &bus = QDBusConnection::sessionBus());
protected:
- /**
- * Get the ConnectionManagerInterface for this ConnectionManager. This
- * method is protected since the convenience methods provided by this
- * class should generally be used instead of calling D-Bus methods
- * directly.
- *
- * \return A pointer to the existing ConnectionManagerInterface for this
- * ConnectionManager
- */
ConnectionManagerInterface *baseInterface() const;
private:
--
1.5.6.5
More information about the Telepathy-commits
mailing list