[SCM] ktp-common-internals packaging branch, master, updated. debian/15.12.1-2-1839-gf0635e9

[Maximiliano Curia]

Gitweb-URL: http://git.debian.org/?p=pkg-kde/applications/ktp-common-internals.git;a=commitdiff;h=34d79af

The following commit has been merged in the master branch:
commit 34d79af3bff5747959a2773da6a28f4695bbb5c3
Author: George Goldberg <george.goldberg at collabora.co.uk>
Date:   Thu Aug 11 15:24:13 2011 +0100

    Fully document the AbstractStorage interface.
---
 kpeople/nepomuk-feeder/abstract-storage.h | 142 +++++++++++++++++++++++++++++-
 1 file changed, 139 insertions(+), 3 deletions(-)

diff --git a/kpeople/nepomuk-feeder/abstract-storage.h b/kpeople/nepomuk-feeder/abstract-storage.h
index 5e31399..ad9c67d 100644
--- a/kpeople/nepomuk-feeder/abstract-storage.h
+++ b/kpeople/nepomuk-feeder/abstract-storage.h
@@ -30,37 +30,173 @@
 #include <TelepathyQt4/Types>
 
 /**
- * Abstract base class for all storage implementations. Primarily to ease
- * unit testing, however, this could potentially be used to replace the Nepomuk
- * storage layer with some other storage layer.
+ * Abstract interface class for storage implementations. This allows fake storage classes to be used
+ * when, e.g. writing unit tests, to remove the need for a sandboxed Nepomuk set up.
+ *
+ * To implement a storage class, subclass this class, implementing all the pure-abstract methods.
  */
 class AbstractStorage : public QObject
 {
     Q_OBJECT
 
 public:
+    /**
+     * Constructor
+     */
     explicit AbstractStorage(QObject *parent = 0);
+
+    /**
+     * Destructor
+     */
     virtual ~AbstractStorage();
 
 public Q_SLOTS:
+    /**
+     * Invoked when a Telepathy Account is constructed.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) of the account
+     * \param protocol the protocol string (e.g. msn or xmpp) of the account
+     */
     virtual void createAccount(const QString &path, const QString &id, const QString &protocol) = 0;
+
+    /**
+     * Invoked when a Telepathy Account is destroyed, e.g. when closing the application. This method
+     * being invoked does not indicate that the Telepathy Account has actually been removed by the
+     * user, simply that the object in the Telepathy Nepomuk Service that wraps the Account has
+     * been destroyed.
+     * 
+     * \param path the object path (unique identifier) of the account
+     */
     virtual void destroyAccount(const QString &path) = 0;
+
+    /**
+     * Invoked to update the nickname of the Telepathy Account.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param nickname the account's nickname
+     */
     virtual void setAccountNickname(const QString &path, const QString &nickname) = 0;
+
+    /**
+     * Invoked to update the presence of the Telepathy Account.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param presence the account's presence
+     */
     virtual void setAccountCurrentPresence(const QString &path, const Tp::SimplePresence &presence) = 0;
+
+    /**
+     * Invoked when the contact list of a Telepathy Account becomes available, this method allows
+     * the storage class to alter accounts that are no longer part of the server-side contact list
+     * as well as batch-adding any contacts to the store that have been added to the server-side
+     * contact list since the last run.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param ids the ids (e.g. me at example.com) of the complete server-side contact list of the account.
+     */
     virtual void cleanupAccountContacts(const QString &path, const QList<QString> &ids) = 0;
 
+
+    /**
+     * Invoked when a Telepathy Contact is constructed.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     */
     virtual void createContact(const QString &path, const QString &id) = 0;
+
+    /**
+     * Invoked when a Telepathy Contact is destroyed, e.g. when closing the application. This method
+     * being invoked does not indicate that the Telepathy Contact has actually been removed by the
+     * user, simply that the object in the Telepathy Nepomuk Service that wraps the Contact has
+     * been destroyed.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     */
     virtual void destroyContact(const QString &path, const QString &id) = 0;
+
+    /**
+     * Invoked to update the alias of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param alias the contact's alias.
+     */
     virtual void setContactAlias(const QString &path, const QString &id, const QString &alias) = 0;
+
+    /**
+     * Invoked to update the presence of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param presence the contact's presence
+     */
     virtual void setContactPresence(const QString &path, const QString &id, const Tp::SimplePresence &presence) = 0;
+
+    /**
+     * Invoked to update the groups to which the Telepahy Contact belongs.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param groups the complete list of groups to which the contact belongs.
+     */
     virtual void setContactGroups(const QString &path, const QString &id, const QStringList &groups) = 0;
+
+    /**
+     * Invoked to update the blocked status of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param blocked indicates whether the contact is blocked or not.
+     */
     virtual void setContactBlockStatus(const QString &path, const QString &id, bool blocked) = 0;
+
+    /**
+     * Invoked to update the presence-publishing state of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param state the presence-publishing state of the contact.
+     */
     virtual void setContactPublishState(const QString &path, const QString &id, const Tp::Contact::PresenceState &state) = 0;
+
+    /**
+     * Invoked to update the presence-subscription state of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param state the presence-subscription state of the contact.
+     */
     virtual void setContactSubscriptionState(const QString &path, const QString &id, const Tp::Contact::PresenceState &state) = 0;
+
+    /**
+     * Invoked to update the capabilities of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param capabilities the complete list of capabilities of the contact.
+     */
     virtual void setContactCapabilities(const QString &path, const QString &id, const Tp::ContactCapabilities &capabilities) = 0;
+
+    /**
+     * Invoked to update the avatar of the Telepathy Contact.
+     *
+     * \param path the object path (unique identifier) of the account
+     * \param id the id (e.g. me at example.com) that in conjunction with the \p path uniquely identifies the contact.
+     * \param avatar the contact's avatar.
+     */
     virtual void setContactAvatar(const QString &path, const QString &id, const Tp::AvatarData &avatar) = 0;
 
 Q_SIGNALS:
+    /**
+     * Signal emitted to indicate whether the storage instance was successfully initialised. The
+     * use of this signal allows for the storage to use asyncrhonous operations to complete its
+     * initialisation.
+     *
+     * \param success indicates whether the storage instance was initialised successfully.
+     */
     void initialised(bool success);
 
 private:

-- 
ktp-common-internals packaging