[Pkg-gnupg-commit] [gpgme] 212/412: Qt: Add some general Protocol documentation

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch master
in repository gpgme.

commit b1f42e8f25ada220ec8e4762cfebc3a49b1f7d56
Author: Andre Heinecke <aheinecke at intevation.de>
Date:   Mon Jul 11 16:41:09 2016 +0200

    Qt: Add some general Protocol documentation
    
    * lang/qt/src/protocol.h (Protocol): Add doc.
    
    --
    This explicitly documents that syncs run with exec need deletion.
---
 lang/qt/src/protocol.h | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/lang/qt/src/protocol.h b/lang/qt/src/protocol.h
index e5153b5..64146b8 100644
--- a/lang/qt/src/protocol.h
+++ b/lang/qt/src/protocol.h
@@ -63,6 +63,41 @@ class ChangePasswdJob;
 class AddUserIDJob;
 class SpecialJob;
 
+/** The main entry point for QGpgME Comes in OpenPGP and SMIME(CMS) flavors.
+ *
+ * Use the proctocol class to obtain an instance of a job. Jobs
+ * provide async API for GnuPG that can be connected to signals / slots.
+ *
+ * A job is usually started with start() and emits a result signal.
+ * The parameters of the result signal depend on the job but the last
+ * two are always a QString for the auditlog and an GpgME::Error for
+ * an eventual error.
+ *
+ * In case async API is used and the result signal is emited a
+ * job schedules its own deletion.
+ *
+ * Most jobs also provide a synchronous call exec in which case
+ * you have to explicitly delete the job if you don't need it anymore.
+ *
+ * \code
+ * // Async example:
+ * KeyListJob *job = openpgp()->keyListJob();
+ * connect(job, &KeyListJob::result, job, [this, job](KeyListResult, std::vector<Key> keys, QString, Error)
+ * {
+ *    // keys and resuls can now be used.
+ * });
+ * \endcode
+ *
+ * \code
+ * // Sync eaxmple:
+ * KeyListJob *job = openpgp()->keyListJob(false, false, false);
+ * std::vector<GpgME::Key> keys;
+ * GpgME::KeyListResult result = job->exec(QStringList() <<
+ *                                         QStringLiteral("alfa at example.net"),
+ *                                         false, keys);
+ * delete job;
+ * \endcode
+ */
 class QGPGME_EXPORT Protocol
 {
 public:

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git