JobScheduler: Improve API docs formatting

GIT_SILENT

src/job/jobscheduler.h

@@ -16,7 +16,8 @@
 
 #include "folderjob.h"
 #include <collection.h>
-// If this define is set, JobScheduler will show debug output, and related kmkernel timers will be shortened
+// If this define is set, JobScheduler will show debug output, and related kmkernel
+// timers will be shortened.
 // This is for debugging purposes only, don't commit with it.
 //#define DEBUG_SCHEDULER
 
@@ -27,33 +28,41 @@ class ScheduledJob;
 /**
  * A scheduled task is some information about a folder job that should be run later.
  * As long as it's not running, it's called a "task", i.e. something that needs to be done.
- * Tasks are held in the JobScheduler.
+ * Tasks are managed by the JobScheduler.
  */
 class MAILCOMMON_EXPORT ScheduledTask
 {
 public:
-    /// Create a scheduled task for a given folder
+    /**
-    /// If @p immediate is true, the scheduler will run this task as soon
+     * Creates a scheduled task for a given folder.
-    /// as possible (but won't interrupt a currently running job for it)
+     * If @p immediate is true, the scheduler will run this task as soon
+     * as possible (but won't interrupt a currently running job for it).
+    */
     ScheduledTask(const Akonadi::Collection &folder, bool immediate);
     virtual ~ScheduledTask();
 
-    /// Run this task, i.e. create a job for it.
+    /**
-    /// Important: the job's execute() method must either call open() on the
+     * Run this task, i.e. create a job for it.
-    /// folder or storage immediately, or abort (deleting itself).
+     * Important: the job's execute() method must either call open() on the folder
-    /// Usually, that job should also be cancellable.
+     * or storage immediately, or abort (deleting itself).
-    /// Otherwise (if the open() is delayed) an unrelated open() could happen first
+     * Usually, that job should also be cancellable.
-    /// and mess things up.
+     * Otherwise (if the open() is delayed) an unrelated open() could happen first
-    /// If for some reason (e.g. folder deleted) nothing should be done, return 0.
+     * and mess things up.
+     * If for some reason (e.g. a folder is deleted) nothing should be done, return 0.
+    */
     virtual ScheduledJob *run() = 0;
 
-    /// An identifier for the type of task (a bit like QListViewItem::rtti)
+    /**
-    /// This allows to automatically prevent two identical tasks from being scheduled
+     * An identifier for the type of task (a bit like QListViewItem::rtti).
-    /// for the same folder. To circumvent this feature and make every task
+     * This allows to automatically prevent two identical tasks from being scheduled
-    /// unique, return 0 here.
+     * for the same folder. To circumvent this feature and make every task unique,
+     * return 0 here.
+     */
     virtual int taskTypeId() const = 0;
 
-    /// The folder which this task is about, 0 if it was deleted meanwhile.
+    /**
+     * The folder which this task is supposed to handle, 0 if it was deleted meanwhile.
+    */
     Q_REQUIRED_RESULT Akonadi::Collection folder() const
     {
         return mCurrentFolder;
@@ -73,7 +82,7 @@ private:
  * The unique JobScheduler instance (owned by kmkernel) implements "background processing"
  * of folder operations (like expiration and compaction). Tasks (things to be done)
  * are registered with the JobScheduler, and it will execute them one at a time,
- * separated with a 1-minute timer. The jobs themselves should use timers to avoid
+ * separated by a 1-minute timer. The jobs themselves should use timers to avoid
  * using too much CPU for too long. Tasks for opened folders are not executed until
  * the folder is closed.
  */
@@ -84,8 +93,10 @@ public:
     explicit JobScheduler(QObject *parent);
     ~JobScheduler();
 
-    /// Register a task to be done for a given folder
+    /**
-    /// The ownership of the task is transferred to the JobScheduler
+     * Register a task to be done for a given folder. The ownership of the task is transferred
+     * to the JobScheduler.
+    */
     void registerTask(ScheduledTask *task);
 
     // D-Bus calls, called from KMKernel
@@ -93,10 +104,10 @@ public:
     void resume();
 
 private:
-    /// Called by a timer to run the next job
+    // Called by a timer to run the next job
     void slotRunNextJob();
 
-    /// Called when the current job terminates
+    // Called when the current job terminates
     void slotJobFinished();
     void restartTimer();
     void interruptCurrentTask();
@@ -115,7 +126,7 @@ private:
 };
 
 /**
- * Base class for scheduled jobs
+ * Base class for scheduled jobs.
  */
 class MAILCOMMON_EXPORT ScheduledJob : public FolderJob
 {