Polished AsyncJob documentation. Removed obsolete job call wrapping notes.

Only the comments have been changed.

diff --git a/src/base/AsyncJob.h b/src/base/AsyncJob.h
index 4a182c5818df4fe6a371914492064a4846010be2..a58dc6dca6452662b60a06c51baaa75ed677b078 100644 (file)
--- a/src/base/AsyncJob.h
+++ b/src/base/AsyncJob.h
@@ -13,26 +13,17 @@
  * AsyncJob is an API and a base for a class that implements a stand-alone
  * "job", "task", or "logical processing thread" which receives asynchronous
  * calls.
- *
- * Implementations should wrap each method receiving an asynchronous call in
- * a pair of macros: AsyncCallEnter and AsyncCallExit. These macros:
- *   - provide call debugging
- *   - trap exceptions and terminate the task if an exception occurs
- *   - ensure that only one asynchronous call is active per object
- * Most of the work is done by AsyncJob class methods. Macros just provide
- * an enter/try/catch/exit framework.
- *
- * Eventually, the macros can and perhaps should be replaced with call/event
- * processing code so that individual job classes do not have to wrap all
- * asynchronous calls.
  */
 
+// See AsyncJobs.dox for details.
+
 /// \ingroup AsyncJobAPI
 class AsyncJob
 {
 
 public:
-    static AsyncJob *AsyncStart(AsyncJob *job); // use this to start jobs
+    /// starts the job (i.e., makes the job asynchronous)
+    static AsyncJob *AsyncStart(AsyncJob *job);
 
     AsyncJob(const char *aTypeName);
     virtual ~AsyncJob();
@@ -45,30 +36,32 @@ protected:
     // Will be replaced with calls to mustStop() when transition is complete.
     void deleteThis(const char *aReason);
 
-    void mustStop(const char *aReason); // force done() for a reason
+    // force done() for a reason but continue with the current method
+    void mustStop(const char *aReason);
 
-    bool done() const; // the job is destroyed in callEnd() when done()
+    bool done() const; ///< the job is destroyed in callEnd() when done()
 
-    virtual void start();
-    virtual bool doneAll() const; // return true when done
-    virtual void swanSong() {}; // perform internal cleanup
-    virtual const char *status() const; // for debugging
+    virtual void start(); ///< called by AsyncStart; do not call directly
+    virtual bool doneAll() const; ///< whether positive goal has been reached
+    virtual void swanSong() {}; ///< internal cleanup; do not call directly
+    virtual const char *status() const; ///< for debugging, starts with space
 
 public:
-    // asynchronous call maintenance
-    bool canBeCalled(AsyncCall &call) const;
-    void callStart(AsyncCall &call);
+    bool canBeCalled(AsyncCall &call) const; ///< whether we can be called
+    void callStart(AsyncCall &call); ///< called just before the called method
+    /// called right after the called job method
+    virtual void callEnd(); ///< called right after the called job method
+    /// called when the job throws during an async call
     virtual void callException(const std::exception &e);
-    virtual void callEnd();
 
 protected:
-    const char *stopReason; // reason for forcing done() to be true
-    const char *typeName; // kid (leaf) class name, for debugging
-    AsyncCall::Pointer inCall; // the asynchronous call being handled, if any
-    const unsigned int id;
+    const char *stopReason; ///< reason for forcing done() to be true
+    const char *typeName; ///< kid (leaf) class name, for debugging
+    AsyncCall::Pointer inCall; ///< the asynchronous call being handled, if any
+    const unsigned int id; ///< unique ID across all strand jobs, unless wraps
 
 private:
-    static unsigned int TheLastId;
+    static unsigned int TheLastId; ///< makes job IDs unique until it wraps
 };