Merge branch 'dah-interface-documentation' into dah

* dah-interface-documentation:
  Small documentation style fixes.
  Updated documentation

Conflicts:
	Plugins/org.commontk.dah.examplehost/ctkExampleDicomHost.h

Plugins/org.commontk.dah.core/ctkDicomAppInterface.h

@@ -31,11 +31,18 @@ struct ctkDicomAppInterface : public ctkDicomExchangeInterface
 
   // Application interface methods
   virtual ctkDicomAppHosting::State getState() = 0;
+  
   /**
-    * 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.
-    */
+   * 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.
+   */
   virtual bool setState(ctkDicomAppHosting::State newState) = 0;
+
+  /**
+   * Method triggered by the host. By calling this method, the Hosting System is asking the Hosted Application to take whatever steps are
+   * needed to make its GUI visible as the topmost window, and to gain focus.
+   * \return TRUE if the Hosted Application received the request and will act on it. Otherwise it returns FALSE
+   */
   virtual bool bringToFront(const QRect& requestedScreenArea) = 0;
 
   // Data exchange interface methods

Plugins/org.commontk.dah.core/ctkDicomAvailableDataHelper.h

@@ -43,11 +43,24 @@ class org_commontk_dah_core_EXPORT ctkDicomAvailableDataAccessor : public QObjec
 public:
   ctkDicomAvailableDataAccessor(ctkDicomAppHosting::AvailableData& ad);
   virtual ~ctkDicomAvailableDataAccessor();
-
+  
+  /**
+   * Method used to retrieve information about a specific patient, giving a patient struct with the ID field already 
+   * defined.
+   * \return the struct with patient information if patient is present inside available data, otherwise return NULL.
+   */
   ctkDicomAppHosting::Patient* getPatient(const ctkDicomAppHosting::Patient& patient) const;
 
+  /**
+   * Method used to retrieve information about a specific study, giving Study UID.
+   * \return the struct with study information if study is present inside available data, otherwise return NULL.
+   */
   ctkDicomAppHosting::Study* getStudy(const QString& studyUID) const;
 
+  /**
+   * Method used to retrieve information about a specific series, giving series UID.
+   * \return the struct with series information if series is present inside available data, otherwise return NULL.
+   */
   ctkDicomAppHosting::Series* getSeries(const QString& seriesUID) const;
 
   void find(const ctkDicomAppHosting::Patient& patient, 

Plugins/org.commontk.dah.core/ctkDicomExchangeInterface.h

@@ -34,6 +34,12 @@ struct ctkDicomExchangeInterface
 
   // Data exchange interface methods
 
+  /**
+   * The source of the data calls this method with descriptions of the available data that it can provide to the
+   * recipient. If the source of the data expects that additional data will become available, it shall pass FALSE
+   * in the lastData parameter. Otherwise, it shall pass TRUE.
+   * \return TRUE if the recipient of the data successfully received the AvailableData list.
+   */
   virtual bool notifyDataAvailable(const ctkDicomAppHosting::AvailableData& data, bool lastData) = 0;
 
   virtual QList<ctkDicomAppHosting::ObjectLocator> getData(
@@ -41,6 +47,10 @@ struct ctkDicomExchangeInterface
     const QList<QUuid>& acceptableTransferSyntaxUIDs,
     bool includeBulkData) = 0;
 
+  /**
+   * The recipient of data invokes this method to release access to binary data provided by the source of the
+   * data through a getData() call. The ArrayOfUUID identifies the data streams that the recipient is releasing.
+   */
   virtual void releaseData(const QList<QUuid>& objectUUIDs) = 0;
 
 //    8.3.3 getAsModels(objectUUIDs : ArrayOfUUID, classUID : UID, supportedInfosetTypes : ArrayOfMimeType) : ModelSetDescriptor	33

Plugins/org.commontk.dah.core/ctkDicomHostInterface.h

@@ -28,10 +28,37 @@
 struct ctkDicomHostInterface: public ctkDicomExchangeInterface
 {
   // Host interface methods
+
+  /**
+   * Returns a newly created DICOM UID that the Hosted Application might use, e.g., to create new data
+   * objects and structures.
+   */
   virtual QString generateUID() = 0;
+
+  /**
+   * The Hosted Application supplies its preferred screen size in the appPreferredScreen parameter. The
+   * Hosting System may utilize this information as a hint, but may return a window location and size that best
+   * suits the Hosting System's GUI.
+   */
   virtual QRect getAvailableScreen(const QRect& preferredScreen) = 0;
+
+  /**
+   * This method returns a URI that a Hosted Application may use to store output that it may provide back to
+   * the Hosting System (e.g. in response to a getData() call).
+   * \return a URI that a Hosted Application may use to store output.
+   */
   virtual QString getOutputLocation(const QStringList& preferredProtocols) = 0;
+
+  /**
+   * The Hosted Application shall invoke this method each time the Hosted Application successfully transitions
+   * to a new state. The new state is passed in the state parameter.
+   */
   virtual void notifyStateChanged(ctkDicomAppHosting::State state) = 0;
+
+  /**
+   * Method used by the Hosted Application to inform the Hosting System of notable events that occur during execution.
+   * The Hosted Application invoks this method, passing the information in the status parameter.
+   */
   virtual void notifyStatus(const ctkDicomAppHosting::Status& status) = 0;
 
   // Data exchange interface methods

Plugins/org.commontk.dah.exampleapp/ctkExampleDicomAppLogic_p.h

@@ -50,9 +50,22 @@ public:
   virtual ~ctkExampleDicomAppLogic();
 
   // ctkDicomAppInterface
+
+  /**
+   * Method triggered by the host. By calling this method, the Hosting System is asking the Hosted Application to take whatever steps are
+   * needed to make its GUI visible as the topmost window, and to gain focus.
+   * \return TRUE if the Hosted Application received the request and will act on it. Otherwise it returns FALSE
+   */
   virtual bool bringToFront(const QRect& requestedScreenArea);
 
   // ctkDicomExchangeInterface
+
+  /**
+   * The source of the data calls this method with descriptions of the available data that it can provide to the
+   * recipient. If the source of the data expects that additional data will become available, it shall pass FALSE
+   * in the lastData parameter. Otherwise, it shall pass TRUE.
+   * \return TRUE if the recipient of the data successfully received the AvailableData list.
+   */
   virtual bool notifyDataAvailable(const ctkDicomAppHosting::AvailableData& data, bool lastData);
 
   virtual QList<ctkDicomAppHosting::ObjectLocator> getData(
@@ -60,9 +73,14 @@ public:
     const QList<QString>& acceptableTransferSyntaxUIDs,
     bool includeBulkData);
 
+  /**
+   * The recipient of data invokes this method to release access to binary data provided by the source of the
+   * data through a getData() call. The ArrayOfUUID identifies the data streams that the recipient is releasing.
+   */
   virtual void releaseData(const QList<QUuid>& objectUUIDs);
 
   // some logic
+  /** Test function for checking */
   void do_something();
 
 

Plugins/org.commontk.dah.examplehost/ctkExampleDicomHost.h

@@ -43,13 +43,46 @@ public:
   virtual ~ctkExampleDicomHost();
 
   virtual void StartApplication(QString AppPath);
+
+  /**
+   * Returns a newly created DICOM UID that the Hosted Application might use, e.g., to create new data
+   * objects and structures.
+   */
   virtual QString generateUID() { return ""; }
+
+  /**
+   * The Hosted Application supplies its preferred screen size in the appPreferredScreen parameter. The
+   * Hosting System may utilize this information as a hint, but may return a window location and size that best
+   * suits the Hosting System's GUI.
+   */
   virtual QRect getAvailableScreen(const QRect& preferredScreen);
+  
+  /**
+   * This method returns a URI that a Hosted Application may use to store output that it may provide back to
+   * the Hosting System (e.g. in response to a getData() call).
+   * \return a URI that a Hosted Application may use to store output.
+   */
   virtual QString getOutputLocation(const QStringList& preferredProtocols);
 
+  /**
+   * Method used by the Hosted Application to inform the Hosting System of notable events that occur during execution.
+   * The Hosted Application invoks this method, passing the information in the status parameter.
+   */
   virtual void notifyStatus(const ctkDicomAppHosting::Status& status);
+
   // exchange methods
+  /**
+   * The source of the data calls this method with descriptions of the available data that it can provide to the
+   * recipient. If the source of the data expects that additional data will become available, it shall pass FALSE
+   * in the lastData parameter. Otherwise, it shall pass TRUE.
+   * \return TRUE if the recipient of the data successfully received the AvailableData list.
+   */
   virtual bool notifyDataAvailable(const ctkDicomAppHosting::AvailableData& data, bool lastData);
+
+  /**
+   * The recipient of data invokes this method to release access to binary data provided by the source of the
+   * data through a getData() call. The ArrayOfUUID identifies the data streams that the recipient is releasing.
+   */
   virtual void releaseData(const QList<QUuid>& objectUUIDs);
 
   ctkDicomAppHosting::State getApplicationState() const;

Plugins/org.commontk.dah.hostedapp/ctkDicomHostService_p.h

@@ -36,13 +36,45 @@ public:
   ctkDicomHostService(ushort port, QString path);
   virtual ~ctkDicomHostService();
 
+  /**
+   * Returns a newly created DICOM UID that the Hosted Application might use, e.g., to create new data
+   * objects and structures.
+   */
   virtual QString generateUID();
+
+  /**
+   * The Hosted Application supplies its preferred screen size in the appPreferredScreen parameter. The
+   * Hosting System may utilize this information as a hint, but may return a window location and size that best
+   * suits the Hosting System's GUI.
+   */
   virtual QRect getAvailableScreen(const QRect& preferredScreen);
+
+  /**
+   * This method returns a URI that a Hosted Application may use to store output that it may provide back to
+   * the Hosting System (e.g. in response to a getData() call).
+   * \return a URI that a Hosted Application may use to store output.
+   */
   virtual QString getOutputLocation(const QStringList& preferredProtocols);
+
+  /**
+   * The Hosted Application shall invoke this method each time the Hosted Application successfully transitions
+   * to a new state. The new state is passed in the state parameter.
+   */
   virtual void notifyStateChanged(ctkDicomAppHosting::State state);
+
+  /**
+   * Method used by the Hosted Application to inform the Hosting System of notable events that occur during execution.
+   * The Hosted Application invoks this method, passing the information in the status parameter.
+   */
   virtual void notifyStatus(const ctkDicomAppHosting::Status& status);
 
   // Exchange methods implemented in ctkDicomExchangeService
+  /**
+   * The source of the data calls this method with descriptions of the available data that it can provide to the
+   * recipient. If the source of the data expects that additional data will become available, it shall pass FALSE
+   * in the lastData parameter. Otherwise, it shall pass TRUE.
+   * \return TRUE if the recipient of the data successfully received the AvailableData list.
+   */
   virtual bool notifyDataAvailable(const ctkDicomAppHosting::AvailableData& data, bool lastData);
 
   virtual QList<ctkDicomAppHosting::ObjectLocator> getData(
@@ -50,6 +82,10 @@ public:
     const QList<QUuid>& acceptableTransferSyntaxUIDs,
     bool includeBulkData);
 
+  /**
+   * The recipient of data invokes this method to release access to binary data provided by the source of the
+   * data through a getData() call. The ArrayOfUUID identifies the data streams that the recipient is releasing.
+   */
   virtual void releaseData(const QList<QUuid>& objectUUIDs);
 
 };