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

List:       kde-commits
Subject:    KDE/kdelibs/kdecore/jobs
From:       Friedrich W. H. Kossebau <kossebau () kde ! org>
Date:       2008-06-26 17:13:33
Message-ID: 1214500413.856423.5432.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 824823 by kossebau:

Apidox change: Be a little more verbose about how to implement start() (and to avoid \
emitResult() inside). Okayed by Kevin O.

 M  +34 -13    kjob.h  


--- trunk/KDE/kdelibs/kdecore/jobs/kjob.h #824822:824823
@@ -34,32 +34,41 @@
  * For all jobs created in an application, the code looks like
  *
  * \code
+ * void SomeClass::methodWithAsynchronousJobCall()
+ * {
  *   KJob * job = someoperation( some parameters );
  *   connect( job, SIGNAL( result( KJob * ) ),
- *            this, SLOT( slotResult( KJob * ) ) );
+ *            this, SLOT( handleResult( KJob * ) ) );
  *   job->start();
+ * }
  * \endcode
  *   (other connects, specific to the job)
  *
- * And slotResult is usually at least:
+ * And handleResult is usually at least:
  *
  * \code
- *  if ( job->error() )
- *      doSomething();
+ * void SomeClass::handleResult( KJob *job )
+ * {
+ *   if ( job->error() )
+ *       doSomething();
+ * }
  * \endcode
  *
  * With the synchronous interface the code looks like
  *
  * \code
- *  KJob *job = someoperation( some parameters );
- *  if ( !job->exec() )
- *  {
- *      // An error occurred
- *  }
- *  else
- *  {
- *      // Do something
- *  }
+ * void SomeClass::methodWithSynchronousJobCall()
+ * {
+ *   KJob *job = someoperation( some parameters );
+ *   if ( !job->exec() )
+ *   {
+ *       // An error occurred
+ *   }
+ *   else
+ *   {
+ *       // Do something
+ *   }
+ * }
  * \endcode
  *
  * @note: KJob and its subclasses is meant to be used 
@@ -131,6 +140,18 @@
     /**
      * Starts the job asynchronously. When the job is finished,
      * result() is emitted.
+     *
+     * This is the method all subclasses need to implement.
+     * It should setup and trigger the workload of the job. It should not do any
+     * work itself. This includes all signals and terminating the job, e.g. by
+     * emitResult(). The workload, which could be another method of the
+     * subclass, is to be triggered using the event loop, e.g. by code like:
+     * \code
+     * void ExampleJob::start()
+     * {
+     *  QTimer::singleShot( 0, this, SLOT( doWork() ) );
+     * }
+     * \endcode
      */
     virtual void start() = 0;
 


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