[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    [kauth] src: update documentation
From:       Harald Sitter <sitter () kde ! org>
Date:       2016-03-01 16:33:35
Message-ID: E1aanEt-0005Jb-2N () scm ! kde ! org
[Download RAW message or body]

Git commit 23dfc62066b1fe41bfe638a4de8b4d6cbe9b5d04 by Harald Sitter.
Committed on 01/03/2016 at 16:32.
Pushed by sitter into branch 'master'.

update documentation

-remove old plunder from Action class documentation. lots of stuff still
 referrred to the old API which didn't use kjob. switch the relevant bits
 over to kjob api
- add a code sample to make it more obvious how to use this
- document bits of ExecuteJob to hopefully get it to show up on api.kde.org

REVIEW: 127243

M  +26   -13   src/kauthaction.h
M  +20   -1    src/kauthexecutejob.h

http://commits.kde.org/kauth/23dfc62066b1fe41bfe638a4de8b4d6cbe9b5d04

diff --git a/src/kauthaction.h b/src/kauthaction.h
index 771ccf2..96f550b 100644
--- a/src/kauthaction.h
+++ b/src/kauthaction.h
@@ -42,21 +42,18 @@ class ActionData;
  * of the Action class with the same name refers to the same action.
  *
  * Once you have an action object you can tell the helper to execute it
- * (asking the user to authenticate if needed) with one of the execute*() methods.
+ * (asking the user to authenticate if needed) with the execute() method.
  * The simplest thing to do is to execute a single action synchronously
- * blocking for the reply, using the execute() method.
+ * blocking for the reply by callin exec() on the job object returned by
+ * execute().
  *
- * For asynchronous calls, use the executeAsync() method. It sends the request
- * to the helper and returns immediately. You can optionally provide an object
- * and a slot. This will be connected to the actionPerformed() signal of the
- * action's ActionWatcher object.
- * By calling the watcher() method, you obtain an object that emits some useful
- * signals that you can receive while the action is in progress. Those signals
- * are emitted also with the synchronous calls.
- * To execute a bunch of actions with a single call, you can use the executeActions()
- * static method. This is not the same as calling executeAsync() for each action,
- * because the actions are execute with a single request to the helper.
- * To use any of the execute*() methods you have to set the default helper's ID using
+ * For asynchronous calls, use KAuth::ExecuteJob::start() instead.
+ * It sends the request
+ * to the helper and returns immediately. Before doing so you should however
+ * connect to at least the KJob::result(KJob *) signal to receive a slot call
+ * once the action is done executing.
+ *
+ * To use the execute() method you have to set the default helper's ID using
  * the setHelperID() static method. Alternatively, you can specify the helperID using
  * the overloaded version of the methods that takes it as a parameter.
  *
@@ -64,6 +61,22 @@ class ActionData;
  * helper when the action is executed. You can access this map using the arguments()
  * method. You can insert into it any kind of custom data you need to pass to the helper.
  *
+ * @code
+ * void MyApp::runAction()
+ * {
+ *     action = KAuth::Action("org.kde.myapp.action");
+ *     KAuth::ExecuteJob *job = action.execute();
+ *     connect(job, &KAuth::ExecuteJob::result, this, &MyApp::actionResult);
+ *     job->start();
+ * }
+ *
+ * void MyApp::actionResult(KJob *kjob)
+ * {
+ *     auto job = qobject_cast<KAuth::ExecuteJob *>(kjob);
+ *     qDebug() << job.error() << job.data();
+ * }
+ * @endcode
+ *
  * @since 4.4
  */
 class KAUTH_EXPORT Action
diff --git a/src/kauthexecutejob.h b/src/kauthexecutejob.h
index 8976c5f..e41fa6f 100644
--- a/src/kauthexecutejob.h
+++ b/src/kauthexecutejob.h
@@ -30,6 +30,10 @@
 namespace KAuth
 {
 
+/**
+ * @brief Job executing an Action
+ * @since 5.0
+ */
 class KAUTH_EXPORT ExecuteJob : public KJob
 {
     Q_OBJECT
@@ -53,11 +57,22 @@ public:
     /// Virtual destructor
     virtual ~ExecuteJob();
 
+    /**
+     * Starts the job asynchronously.
+     * @see KJob::result
+     * @see newData
+     * @see statusChanged
+     */
     void start() Q_DECL_OVERRIDE;
 
-    /// Returns the action associated with this job
+    /**
+     * @returns the action associated with this job
+     */
     Action action() const;
 
+    /**
+     * @returns the data sent by the helper
+     */
     QVariantMap data() const;
 
 Q_SIGNALS:
@@ -76,6 +91,10 @@ Q_SIGNALS:
     */
     void newData(const QVariantMap &data);
 
+    /**
+     * @brief Signal emitted when the authentication status changes
+     * @param status the the new authentication status
+     */
     void statusChanged(KAuth::Action::AuthStatus status);
 };
 
[prev in list] [next in list] [prev in thread] [next in thread]