abstractHost and abstractApp documented

todo: document examples

Plugins/org.commontk.dah.app/ctkDicomAbstractApp.h

@@ -32,13 +32,14 @@ class ctkPluginContext;
 class ctkDicomObjectLocatorCache;
 
 /**
-  * Provides a basic implementation for an application app.
-  *
-  * TODO: provide helper/convenience methods to ease application development
-  *
-  * The methods of the ctkDicomAppInterface have to be implemented for the business logic,
-  *
-  */
+ * @brief Provides a basic implementation for an application app.
+ *
+ * The methods of the ctkDicomAppInterface have to be implemented for the business logic.
+ *
+ * @todo Provide helper/convenience methods to ease application development.
+ *
+ *
+*/
 class org_commontk_dah_app_EXPORT ctkDicomAbstractApp : public QObject, public ctkDicomAppInterface
 {
   Q_OBJECT
@@ -46,38 +47,138 @@ class org_commontk_dah_app_EXPORT ctkDicomAbstractApp : public QObject, public c
 
 public:
 
+  /**
+   * @brief
+   *
+   * @param context
+  */
   ctkDicomAbstractApp(ctkPluginContext* context);
+
+  /**
+   * @brief
+   *
+  */
   virtual ~ctkDicomAbstractApp();
 
+
   /**
-    * Method triggered by the host. Changes the state of the hosted application.
-    * @return true if state received and not illegal in the transition diagram from the reference, false if illegal or not recognized.
-    */
+   * @brief Method triggered by the host. Changes the state of the hosted application.
+   *
+   * Goes through the transitions and emits signals when relevant to trigger actions. Checks for the legality of a transition.
+   *
+   * @see startProgress() resumeProgress() suspendProgress() cancelProgress() exitHostedApp() releaseResources()
+   * @param newState
+   * @return bool true if state received and not illegal in the transition diagram from the reference, false if illegal or not recognized.
+  */
   virtual bool setState(ctkDicomAppHosting::State newState);
+
+  /**
+   * @brief Sends the current state the app is in to the hosting system.
+   *
+   * @return ctkDicomAppHosting::State
+  */
   virtual ctkDicomAppHosting::State getState();
+
+  /**
+   * @brief Gets ctkDicomAppHosting::ObjectLocators from the hosting system.
+   *
+   * @param objectUUIDs
+   * @param acceptableTransferSyntaxUIDs
+   * @param includeBulkData
+   * @return QList<ctkDicomAppHosting::ObjectLocator>
+  */
   virtual QList<ctkDicomAppHosting::ObjectLocator> getData(
     const QList<QUuid>& objectUUIDs,
     const QList<QString>& acceptableTransferSyntaxUIDs,
     bool includeBulkData);
 
+  /**
+   * @brief
+   *
+   * @return ctkDicomObjectLocatorCache *
+  */
   ctkDicomObjectLocatorCache* objectLocatorCache()const;
 
+  /**
+   * @brief
+   *
+   * @param availableData
+   * @param lastData
+   * @return bool
+  */
   bool publishData(const ctkDicomAppHosting::AvailableData& availableData, bool lastData);
 
 protected:
+  /**
+   * @brief Gets a handle to the host, in order to call methods on it.
+   *
+   * @return ctkDicomHostInterface *
+  */
   virtual ctkDicomHostInterface* getHostInterface() const;
- void setInternalState(ctkDicomAppHosting::State state);
+
+  /**
+   * @brief Sets the internal representation of the current state.
+   *
+   * @param state
+  */
+  void setInternalState(ctkDicomAppHosting::State state);
+
 signals:
+  /**
+   * @brief ctkDicomAppHosting::INPROGRESS state received and legal.
+   *
+   * the slot connected to this is responsible for notifying the hosting service that it is really in progress by a call to getHostInterface()->notifyStateChanged(ctkDicomAppHosting::INPROGRESS);
+   *
+  */
   void startProgress();
+
+  /**
+   * @brief ctkDicomAppHosting::INPROGRESS state received when the app is in the ctkDicomAppHosting::SUSPENDED state.
+   *
+   * Corresponding slot responsible for calling getHostInterface()->notifyStateChanged(ctkDicomAppHosting::INPROGRESS); when resumed.
+   *
+  */
   void resumeProgress();
+
+  /**
+   * @brief ctkDicomAppHosting::SUSPENDED state received.
+   *
+   * Corresponding slot responsible for calling getHostInterface()->notifyStateChanged(ctkDicomAppHosting::SUSPENDED); when resources have been released.
+   *
+  */
   void suspendProgress();
+
+  /**
+   * @brief ctkDicomAppHosting::CANCELED state received.
+   *
+   * The CANCELED state is particular because it leads to ctkDicomAppHosting::IDLE when the app has canceled the process.
+   * Therefore the notification the app entered this CANCELED state is sent straight away by the setState method.
+   *
+   * The slot connected to this signal MUST NOT notify CANCELED, but MUST notify IDLE when the resources have been released.
+   *
+  */
   void cancelProgress();
+
+  /**
+   * @brief ctkDicomAppHosting::EXIT state received and legal.
+   *
+   * An EXIT notification is sent by setState, no communication with the hosting system is needed anymore.
+   * A slot connected to this should stop the application process for good.
+   *
+  */
   void exitHostedApp();
+
+  /**
+   * @brief ctkDicomAppHosting::IDLE state received and legal.
+   *
+   * It means the current state was COMPLETED, and it is now time to release the resources, the hosting system doesn't need them any more.
+   *
+  */
   void releaseResources();
 
 private:
   Q_DECLARE_PRIVATE(ctkDicomAbstractApp)
-  const QScopedPointer<ctkDicomAbstractAppPrivate> d_ptr;
+  const QScopedPointer<ctkDicomAbstractAppPrivate> d_ptr; /**< TODO */
 };
 
 #endif // CTKDICOMABSTRACTAPP_H

Plugins/org.commontk.dah.host/ctkDicomAbstractHost.h

@@ -31,16 +31,15 @@
 class ctkDicomAbstractHostPrivate;
 class ctkDicomObjectLocatorCache;
 
-
 /**
-  * Provides a basic implementation for an application host.
-  *
-  * It starts a http server and serves one hosted application. Multiple instances
-  * can be used for hosting multiple applications.
-  *
-  * The methods of the ctkDicomHostInterface have to be implemented for the business logic,
-  *
-  */
+ * @brief Provides a basic implementation for an application host.
+ *
+ * It starts a http server and serves one hosted application. Multiple instances
+ * can be used for hosting multiple applications.
+ *
+ * The methods of the ctkDicomHostInterface have to be implemented for the business logic,
+ *
+*/
 class org_commontk_dah_host_EXPORT ctkDicomAbstractHost : public QObject, public ctkDicomHostInterface
 {
  Q_OBJECT
@@ -49,43 +48,157 @@ class org_commontk_dah_host_EXPORT ctkDicomAbstractHost : public QObject, public
 public:
 
   /**
-    * Starts the soap sever on the specified port or choose port automatically.
-    */
+   * @brief Starts the soap sever on the specified port or choose port automatically.
+   *
+   * @param hostPort
+   * @param appPort
+  */
   ctkDicomAbstractHost(int hostPort = 0, int appPort = 0);
+
+  /**
+   * @brief
+   *
+  */
   virtual ~ctkDicomAbstractHost();
+
+  /**
+   * @brief Gets the host port.
+   *
+   * @return int
+  */
   int getHostPort() const;
 
+  /**
+   * @brief Gets the hosted application port.
+   *
+   * @return int
+  */
   int getAppPort() const;
 
+  /**
+   * @brief Handles transitions form one state to the other.
+   * When a new state notification arrives from the hosted app,
+   * it goes through a state machine check and triggers signals depending on the appropriate response.
+   *
+   * The developer must connect to these signals to react to new state. The signal #stateChangedReceived is not to be used for this, it is just there for propagating new states for information only.
+   *
+   * @see appReady() releaseAvailableResources() startProgress() resumed() completed() suspended() canceled() exited() stateChangedReceived()
+   * @param state
+  */
   virtual void notifyStateChanged(ctkDicomAppHosting::State state);
-ctkDicomAppHosting::State getApplicationState()const;
+
+  /**
+   * @brief Gets the internal representation of the application state.
+   * Does not call the client. For that purpose call ctkDicomAppInterface::getState() instead.
+   *
+   * @return ctkDicomAppHosting::State
+  */
+  ctkDicomAppHosting::State getApplicationState()const;
+
+  /**
+   * @brief Gets the application service in order to call methods on the hosted app.
+   *
+   * @return ctkDicomAppInterface *
+  */
   ctkDicomAppInterface* getDicomAppService() const;
 
+  /**
+   * @brief Gets ctkDicomAppHosting::ObjectLocators from the hosted app.
+   *
+   * @param objectUUIDs
+   * @param acceptableTransferSyntaxUIDs
+   * @param includeBulkData
+   * @return QList<ctkDicomAppHosting::ObjectLocator>
+  */
   virtual QList<ctkDicomAppHosting::ObjectLocator> getData(
     const QList<QUuid>& objectUUIDs,
     const QList<QString>& acceptableTransferSyntaxUIDs,
     bool includeBulkData);
 
+  /**
+   * @brief
+   *
+   * @return ctkDicomObjectLocatorCache *
+  */
   ctkDicomObjectLocatorCache* objectLocatorCache()const;
 
+  /**
+   * @brief
+   *
+   * @param availableData
+   * @param lastData
+   * @return bool
+  */
   bool publishData(const ctkDicomAppHosting::AvailableData& availableData, bool lastData);
 
 signals:
- void appReady();
- void releaseAvailableResources();
- void startProgress();
- void resumed();
- void completed();
- void suspended();
- void canceled();
- void exited();
- void stateChangedReceived(ctkDicomAppHosting::State state);
- void statusReceived(const ctkDicomAppHosting::Status& status);
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::IDLE state notification has been received, and the previous state was EXIT, IDLE or CANCELED.
+   * @todo: perhaps also send this when completed. Needs discussion.
+   *
+  */
+  void appReady();
+
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::IDLE state notification has been received, and the previous state was COMPLETED.
+   *
+  */
+  void releaseAvailableResources();
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::INPROGRESS state notification has been received, and previous state IDLE.
+   *
+  */
+  void startProgress();
+
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::INPROGRESS state notification has been received, and previous state SUSPENDED.
+   *
+  */
+  void resumed();
+
+  /**
+   * @brief  Emitted when the ctkDicomAppHosting::COMPLETED state notification has been received.
+   *
+  */
+  void completed();
+
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::SUSPENDED state notification has been received.
+   *
+  */
+  void suspended();
+
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::CANCELED state notification has been received.
+   *
+  */
+  void canceled();
+
+  /**
+   * @brief Emitted when the ctkDicomAppHosting::EXIT state notification has been received.
+   *
+  */
+  void exited();
+
+  /**
+   * @brief Emitted after any new state has been received.
+   * The event is sent after all the others have been sent through the state machine.
+   *
+   * @param state
+  */
+  void stateChangedReceived(ctkDicomAppHosting::State state);
+
+  /**
+   * @brief
+   *
+   * @param status
+  */
+  void statusReceived(const ctkDicomAppHosting::Status& status);
 
 private:
 
   Q_DECLARE_PRIVATE(ctkDicomAbstractHost)
-  const QScopedPointer<ctkDicomAbstractHostPrivate> d_ptr;
+  const QScopedPointer<ctkDicomAbstractHostPrivate> d_ptr; /**< TODO */
 
 };