Added API and XSD file documentation.

CMakeLists.txt

@@ -877,6 +877,9 @@ foreach(lib ${CTK_LIBS})
   endif()
 endforeach()
 
+# Add the CommandLineModules root directory for additional processing
+add_subdirectory(Libs/CommandLineModules)
+
 #-----------------------------------------------------------------------------
 if(CTK_USE_QTTESTING)
   add_subdirectory(Libs/QtTesting)
@@ -911,10 +914,6 @@ endif()
 #add_subdirectory(Testing)
 #add_subdirectory(Examples)
 
-if (BUILD_TESTING AND
-    CTK_LIB_CommandLineModules/Core AND CTK_LIB_CommandLineModules/Backend/LocalProcess)
-  add_subdirectory(Libs/CommandLineModules/Testing)
-endif()
 
 #-----------------------------------------------------------------------------
 # Style Checking configuration

Libs/CommandLineModules/Backend/FunctionPointer/README.md

@@ -0,0 +1,13 @@
+Function Pointer (experimental)    {#CommandLineModulesBackendFunctionPointer_Page}
+===============================
+
+The Function Pointer back-end is an experimental *proof-of-concept* (however, it is used in
+some unit tests as a light-weight back-end).
+
+This back-end allows the registration of C/C++ function pointers and uses template magic
+to auto-generate an XML description using the type information in the function signature.
+Many template specializations for certain parameter types are missing, hence this back-end
+will only work for a limited set of argument types. See the ctkCmdLineModuleBackendFunctionPointer
+class for more information.
+
+See the \ref CommandLineModulesBackendFunctionPointer_API module for the API documentation.

Libs/CommandLineModules/Backend/FunctionPointer/ctkCmdLineModuleBackendFunctionPointer.h

@@ -94,7 +94,10 @@ struct ctkCmdLineModuleBackendFunctionPointerPrivate;
 /**
  * \class ctkCmdLineModuleBackendFunctionPointer
  * \brief Provides a back-end implementation to enable directly calling a function pointer.
- * \ingroup CommandLineModulesBackendFunctionPointer
+ * \ingroup CommandLineModulesBackendFunctionPointer_API
+ *
+ * \warning This back-end is highly experimental and will not work for most function pointers when
+ *          trying to register them via registerFunctionPointer().
  */
 class CTK_CMDLINEMODULEBACKENDFP_EXPORT ctkCmdLineModuleBackendFunctionPointer : public ctkCmdLineModuleBackend
 {

Libs/CommandLineModules/Backend/FunctionPointer/ctkCmdLineModuleFunctionPointerTask_p.h

@@ -32,7 +32,7 @@
  * \class ctkCmdLineModuleFunctionPointerTask
  * \brief Provides a ctkCmdLineModuleFutureInterface implementation specifically to
  * run a function pointer asynchronousely.
- * \ingroup CommandLineModulesBackendFunctionPointer
+ * \ingroup CommandLineModulesBackendFunctionPointer_API
  */
 class ctkCmdLineModuleFunctionPointerTask : public ctkCmdLineModuleFutureInterface, public QRunnable
 {

Libs/CommandLineModules/Backend/LocalProcess/README.md

@@ -0,0 +1,9 @@
+Local Process    {#CommandLineModulesBackendLocalProcess_Page}
+=============
+
+The Local Process back-end is a fully featured back-end implementation for handling executable
+modules. When registered with a ctkCmdLineModuleManager instance, it will handle the registration
+of all modules with a "file" location URL scheme. See the ctkCmdLineModuleBackendLocalProcess class
+for details.
+
+See the \ref CommandLineModulesBackendLocalProcess_API module for the API documentation.

Libs/CommandLineModules/Backend/LocalProcess/ctkCmdLineModuleBackendLocalProcess.h

@@ -31,10 +31,23 @@
 struct ctkCmdLineModuleBackendLocalProcessPrivate;
 
 /**
- * \class ctkCmdLineModuleBackendLocalProcess
- * \brief Provides an ctkCmdLineModuleBackend implementation
+ * @ingroup CommandLineModulesBackendLocalProcess_API
+ *
+ * @brief Provides an ctkCmdLineModuleBackend implementation
  * to run a locally installed command line application.
- * \ingroup CommandLineModulesBackendLocalProcess
+ *
+ * Use this back-end if you want to be able to register local executables as command
+ * line modules. The back-end handles the "file" URL scheme, allowing you to register
+ * modules with the ctkCmdLineModuleManager by using
+ * @code
+ * ctkCmdLineModuleManager::registerModule(QUrl::fromLocalFile("/path/to/executable"));
+ * @endcode
+ *
+ * The XML description for a module is extracted from the standard output of the
+ * executable when calling it with the \c ––xml command line argument.
+ *
+ * The ctkCmdLineModuleFuture returned by run() allows cancelation by killing the running
+ * process. On Unix systems, it also allows to pause it.
  */
 class CTK_CMDLINEMODULEBACKENDLP_EXPORT ctkCmdLineModuleBackendLocalProcess : public ctkCmdLineModuleBackend
 {
@@ -47,12 +60,34 @@ public:
   virtual QString name() const;
   virtual QString description() const;
 
+  /**
+   * @brief This back-end can handle the "file" URL scheme.
+   * @return Returns the schemes this back-end can handle.
+   */
   virtual QList<QString> schemes() const;
 
+  /**
+   * @brief Returns the last modified time of the module at \c location.
+   * @param location The location URL of the module for which to get the timestamp.
+   * @return A timestamp.
+   */
   virtual qint64 timeStamp(const QUrl &location) const;
 
+  /**
+   * @brief Get the raw XML description from the module at \c location.
+   * @param location The location URL of the module for which to get the XML description.
+   * @return The raw XML description.
+   *
+   * This method always calls the executable with a \c &ndash;&ndash;xml argument and returns
+   * the complete data emitted on the standard output channel.
+   */
   virtual QByteArray rawXmlDescription(const QUrl& location);
 
+  /**
+   * @brief Run a front-end for this module in a local process.
+   * @param frontend The front-end to run.
+   * @return A future object for communicating with the running process.
+   */
   virtual ctkCmdLineModuleFuture run(ctkCmdLineModuleFrontend *frontend);
 
 private:

Libs/CommandLineModules/Backend/LocalProcess/ctkCmdLineModuleProcessTask.h

@@ -41,7 +41,7 @@ struct ctkCmdLineModuleProcessTaskPrivate;
  * \class ctkCmdLineModuleProcessTask
  * \brief Implements ctkCmdLineModuleFutureInterface to enabling
  * running a command line application asynchronously.
- * \ingroup CommandLineModulesBackendLocalProcess
+ * \ingroup CommandLineModulesBackendLocalProcess_API
  */
 class CTK_CMDLINEMODULEBACKENDLP_EXPORT ctkCmdLineModuleProcessTask
     : public ctkCmdLineModuleFutureInterface, public QRunnable

Libs/CommandLineModules/Backend/LocalProcess/ctkCmdLineModuleProcessWatcher_p.h

@@ -36,7 +36,7 @@ class QProcess;
 /**
  * \class ctkCmdLineModuleProcessWatcher
  * \brief Provides progress updates using QFutureWatcher
- * \ingroup CommandLineModulesBackendLocalProcess
+ * \ingroup CommandLineModulesBackendLocalProcess_API
  */
 class ctkCmdLineModuleProcessWatcher : public QObject
 {

Libs/CommandLineModules/CMakeLists.txt

@@ -0,0 +1,11 @@
+
+find_package(Doxygen)
+
+if(DOXYGEN_FOUND)
+  add_subdirectory(Documentation)
+endif()
+
+if(BUILD_TESTING AND
+    CTK_LIB_CommandLineModules/Core AND CTK_LIB_CommandLineModules/Backend/LocalProcess)
+  add_subdirectory(Testing)
+endif()

Libs/CommandLineModules/Core/CMakeLists.txt

@@ -104,6 +104,14 @@ if(CTK_WRAP_PYTHONQT_FULL OR CTK_WRAP_PYTHONQT_LIGHT)
     )
 endif()
 
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+  # Copy XML schema file to the Doxygen output directory
+  add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/Resources/ctkCmdLineModule.xsd
+                                                  ${CTK_BINARY_DIR}/Documentation/html/ctkCmdLineModule.xsd)
+endif()
+
 # Testing
 if(BUILD_TESTING)
   add_subdirectory(Testing)

Libs/CommandLineModules/Core/README.md

@@ -0,0 +1,9 @@
+Core    {#CommandLineModulesCore_Page}
+====
+
+The Command Line Modules Core library provides high-level classes to manage command line modules.
+
+It provides abstract classes for working with back and front ends and a central management class
+for registering and running modules, the ctkCmdLineModuleManager.
+
+See the \ref CommandLineModulesCore_API module for the API documentation.

Libs/CommandLineModules/Core/Resources/ctkCmdLineModule.xsd

@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="xs3p.xsl"?>
 
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
@@ -9,21 +10,82 @@
   ===================================================================
   -->
   <xsd:element name="executable">
+    <xsd:annotation>
+      <xsd:documentation>The root element for each module XML description. It must contain
+      at least one "parameters" element.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexType>
       <xsd:sequence>
-      
         <!-- 'title' and 'description' elements are required -->
-        <xsd:element maxOccurs="1" minOccurs="0" name="category" type="xsd:string"/>
-        <xsd:element maxOccurs="1" name="title" type="xsd:string"/>
-        <xsd:element maxOccurs="1" name="description" type="xsd:string"/>
-        <xsd:element maxOccurs="1" minOccurs="0" name="version" type="xsd:string"/>
-        <xsd:element maxOccurs="1" minOccurs="0" name="documentation-url" type="xsd:string"/>
-        <xsd:element maxOccurs="1" minOccurs="0" name="license" type="xsd:string"/>
-        <xsd:element maxOccurs="1" minOccurs="0" name="contributor" type="xsd:string"/>
-        <xsd:element maxOccurs="1" minOccurs="0" name="acknowledgements" type="xsd:string"/>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="category" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>Classifies the module (e.g. Filtering, Segmentation).
+            The value can be a dot separated string to create category hierarchies.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" name="title" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A human-readable name for the module.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" name="description" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A detailed description of the modules purpose.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="version" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>The modules version number. A suggested format is:
+            &lt;p&gt;
+            major.minor.patch.build.status
+            &lt;/p&gt;&lt;p&gt;
+            where status is one of
+            &lt;ul&gt;
+              &lt;li&gt;vc: version controlled (pre-alpha), build can be a serial revision number, if any (like svn might have).&lt;/li&gt;
+              &lt;li&gt;a: alpha&lt;/li&gt;
+              &lt;li&gt;b: beta&lt;/li&gt;
+              &lt;li&gt;rc: release candidate&lt;/li&gt;
+              &lt;li&gt;fcs: first customer ship&lt;/li&gt;
+            &lt;/ul&gt;
+            &lt;/p&gt;
+            </xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="documentation-url" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A URL pointing to a documentation or home page of the module.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="license" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>The type of license or a URL containing the license.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="contributor" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>The author(s) of the command line module.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
+        
+        <xsd:element maxOccurs="1" minOccurs="0" name="acknowledgements" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>Acknowledgements for funding agency, employer, colleague, etc.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
         
         <!-- Parameter group elements -->
-        <xsd:element maxOccurs="unbounded" name="parameters" type="parameters"/>
+        <xsd:element maxOccurs="unbounded" name="parameters" type="parameters">
+          <xsd:annotation>
+            <xsd:documentation>Starts a group of parameters.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
       </xsd:sequence>
     </xsd:complexType>
   </xsd:element>
@@ -34,44 +96,74 @@
   ===================================================================
   -->
   <xsd:complexType name="parameters">
+    <xsd:annotation>
+      <xsd:documentation>Starts a group of parameters.</xsd:documentation>
+    </xsd:annotation>
+    
     <xsd:sequence>
     
       <!-- Required elements for a parameter group -->
-      <xsd:element name="label" type="xsd:string"/>
-      <xsd:element name="description" type="xsd:string"/>
+      <xsd:element name="label" type="xsd:string">
+        <xsd:annotation>
+          <xsd:documentation>A short string used as the label for this group.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+        
+      <xsd:element name="description" type="xsd:string">
+        <xsd:annotation>
+          <xsd:documentation>A description of this parameter group.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+        
       
       <!-- At least one parameter definition is required in the group -->
       <xsd:choice maxOccurs="unbounded">
-        <xsd:element name="integer" type="scalarType"/>
-        <xsd:element name="integer-vector" type="scalarVectorType"/>
+      
         <xsd:element name="boolean" type="paramType"/>
+        
+        <xsd:element name="integer" type="scalarType"/>
         <xsd:element name="float" type="scalarType"/>
-        <xsd:element name="float-vector" type="scalarVectorType"/>
         <xsd:element name="double" type="scalarType"/>
-        <xsd:element name="double-vector" type="scalarVectorType"/>
+        
         <xsd:element name="string" type="multipleType"/>
+        <xsd:element name="directory" type="multipleType"/>
+
+        <xsd:element name="integer-vector" type="scalarVectorType"/>
+        <xsd:element name="float-vector" type="scalarVectorType"/>
+        <xsd:element name="double-vector" type="scalarVectorType"/>
+        
         <xsd:element name="string-vector" type="paramType"/>
-        <xsd:element name="point" type="pointType"/>
-        <xsd:element name="region" type="pointType"/>
-        <xsd:element name="string-enumeration" type="enumerationType"/>
+        
         <xsd:element name="integer-enumeration" type="enumerationType"/>
         <xsd:element name="float-enumeration" type="enumerationType"/>
         <xsd:element name="double-enumeration" type="enumerationType"/>
+        <xsd:element name="string-enumeration" type="enumerationType"/>
+        
+        
+        <xsd:element name="point" type="pointType"/>
+        <xsd:element name="region" type="pointType"/>
+        
         <xsd:element name="file" type="fileType"/>
-        <xsd:element name="directory" type="multipleType"/>
         <xsd:element name="image" type="imageType"/>
         <xsd:element name="geometry" type="geometryType"/>
+        
         <!--
         <xsd:element name="transform" type="transformType"/>
         <xsd:element name="table" type="tableType"/>
         <xsd:element name="measurement" type="measurementType"/>
         -->
+        
       </xsd:choice>
       
     </xsd:sequence>
     
     <!-- Parameter group attributes -->
-    <xsd:attribute default="false" name="advanced" type="xsd:boolean"/>
+    <xsd:attribute default="false" name="advanced" type="xsd:boolean">
+      <xsd:annotation>
+        <xsd:documentation>This value is usually used in GUI generators to decide
+        if the parameters belonging to this group should be initially hidden to the user or not.</xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
   </xsd:complexType>
 
   <!--
@@ -81,9 +173,17 @@
   ===================================================================
   -->
   <xsd:complexType name="paramType">
+    <xsd:annotation>
+      <xsd:documentation>This type specifies elements common to all parameter types.</xsd:documentation>
+    </xsd:annotation>
+        
     <xsd:sequence>
 
       <xsd:element name="name">
+        <xsd:annotation>
+          <xsd:documentation>The unique name (within this module) of the parameter. This is only used internally.</xsd:documentation>
+        </xsd:annotation>
+        
         <xsd:simpleType>
           <xsd:restriction base="xsd:string">
             <xsd:pattern value="[_a-zA-Z][_a-zA-Z0-9]*"/>
@@ -93,20 +193,54 @@
 
       <!-- either 'flag' or 'longflag' (or both) or 'index' are required -->
       <xsd:choice>
+        <xsd:annotation>
+          <xsd:documentation>You must either specify "flag" or "longflag" (or both) or "index".</xsd:documentation>
+        </xsd:annotation>
         <xsd:sequence>
           <xsd:element maxOccurs="1" name="flag" type="flagType"/>
           <xsd:element minOccurs="0" maxOccurs="1" name="longflag" type="longFlagType"/>
         </xsd:sequence>
         <xsd:element name="longflag" type="longFlagType"/>
-        <xsd:element name="index" type="xsd:nonNegativeInteger"/>
+        <xsd:element name="index" type="xsd:nonNegativeInteger">
+          <xsd:annotation>
+            <xsd:documentation>An integer starting at 0, that specifies a module argument that has no flags.
+            The index value 1000 is reserved as a marker for output parameters (see the "channel" element) to indicate that
+            this parameter is used to return results during the execution of this module and does not need to be set.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:element>
       </xsd:choice>
 
-      <xsd:element name="description" type="xsd:string"/>
-      <xsd:element name="label" type="xsd:string"/>
-      <xsd:element minOccurs="0" name="default" type="xsd:string"/>
+      <xsd:element name="description" type="xsd:string">
+        <xsd:annotation>
+          <xsd:documentation>A brief description of the parameter.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      
+      <xsd:element name="label" type="xsd:string">
+        <xsd:annotation>
+          <xsd:documentation>A label for parameter.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      
+      <xsd:element minOccurs="0" name="default" type="xsd:string">
+        <xsd:annotation>
+          <xsd:documentation>A default value for the parameter. The default must be a type that is compatible with the
+          parameter type. The vector parameters are specified as comma separated values of the atomic parameter type.
+          </xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
       
       <!-- the 'channel' element is optional -->
       <xsd:element minOccurs="0" maxOccurs="1" name="channel">
+        <xsd:annotation>
+          <xsd:documentation>Specifies whether the parameter is an input or output parameter. Output parameters can for
+          example specify file paths where to write output data (e.g. using the "image" element) or they can represent
+          "simple return parameters", indicated by providing an "index" of 1000. The current values of suche simple return
+          parameters are not passed to the module during its execution. Rather, the module itself reports these parameter
+          values during execution.
+          </xsd:documentation>
+        </xsd:annotation>
+        
         <xsd:simpleType>
           <xsd:restriction base="xsd:string">
             <xsd:enumeration value="input"/>
@@ -128,6 +262,10 @@
   ===================================================================
   -->
   <xsd:complexType name="scalarVectorType">
+    <xsd:annotation>
+      <xsd:documentation>This type represents vectors of integers, floats, and doubles and can contain
+      constraints on the domain of valid values for the vector elements.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexContent>
       <xsd:extension base="paramType">
         <xsd:sequence>
@@ -144,9 +282,18 @@
   ===================================================================
   -->
   <xsd:complexType name="multipleType">
+    <xsd:annotation>
+      <xsd:documentation>Parameters of this type are allowed to be passed multiple times with
+      different values to the module if the attribute "multiple" is set to true. Note that if such
+      a parameter has no flags, its values must be passed as the last arguments to the module.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexContent>
       <xsd:extension base="paramType">
-        <xsd:attribute default="false" name="multiple" type="xsd:boolean"/>
+        <xsd:attribute default="false" name="multiple" type="xsd:boolean">
+          <xsd:annotation>
+            <xsd:documentation>Allows this parameter to occur multiple times.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
       </xsd:extension>
     </xsd:complexContent>
   </xsd:complexType>
@@ -158,6 +305,10 @@
   ===================================================================
   -->
   <xsd:complexType name="scalarType">
+    <xsd:annotation>
+      <xsd:documentation>This type represents integers, floats, and doubles and can contain
+      constraints on the domain of valid values.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexContent>
       <xsd:extension base="multipleType">
         <xsd:sequence>
@@ -174,10 +325,18 @@
   ===================================================================
   -->
   <xsd:complexType name="enumerationType">
+    <xsd:annotation>
+      <xsd:documentation>Restricts the valid parameter value to one and only one element out of
+      a specified descrete set of values.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexContent>
       <xsd:extension base="paramType">
         <xsd:sequence>
-          <xsd:element maxOccurs="unbounded" name="element" type="xsd:string"/>
+          <xsd:element maxOccurs="unbounded" name="element" type="xsd:string">
+            <xsd:annotation>
+              <xsd:documentation>Defines one possible enumeration value.</xsd:documentation>
+            </xsd:annotation>
+          </xsd:element>
         </xsd:sequence>
       </xsd:extension>
     </xsd:complexContent>
@@ -190,9 +349,23 @@
   ===================================================================
   -->
   <xsd:complexType name="pointType">
+    <xsd:annotation>
+      <xsd:documentation>A parameter describing a point or region in 3D with a specified coordinate system.</xsd:documentation>
+    </xsd:annotation>
     <xsd:complexContent>
       <xsd:extension base="multipleType">
         <xsd:attribute name="coordinateSystem">
+          <xsd:annotation>
+            <xsd:documentation>Specifies the coordinate system. If unspecified, the executing module is free to interpret the
+            coordinates in the most appropriate way. For more information about the different systems, see
+            &lt;a href="http://www.slicer.org/slicerWiki/index.php/Coordinate_systems"&gt;Coordinate Systems&lt;/a&gt;.
+            &lt;ul&gt;
+            &lt;li&gt;&lt;b&gt;ras&lt;/b&gt; (Right, Anterior, Superior) coordinate system.&lt;/li&gt;
+            &lt;li&gt;&lt;b&gt;ijk&lt;/b&gt; image coordinate system.&lt;/li&gt;
+            &lt;li&gt;&lt;b&gt;lps&lt;/b&gt; (Left, Posterior, Superior) coordinate system.&lt;/li&gt;
+            &lt;/ul&gt;
+            </xsd:documentation>
+          </xsd:annotation>
           <xsd:simpleType>
             <xsd:restriction base="xsd:string">
               <xsd:enumeration value="ras"/>
@@ -214,8 +387,15 @@
   <xsd:complexType name="geometryType">
     <xsd:complexContent>
       <xsd:extension base="multipleType">
-        <xsd:attribute name="fileExtensions" type="xsd:string"/>
+        <xsd:attribute name="fileExtensions" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of allowed file extensions.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
         <xsd:attribute name="type">
+          <xsd:annotation>
+            <xsd:documentation>Optionally specifies the allowed geometry type.</xsd:documentation>
+          </xsd:annotation>
           <xsd:simpleType>
             <xsd:restriction base="xsd:string">
               <xsd:enumeration value="fiberbundle"/>
@@ -230,14 +410,18 @@
   <!--
   ===================================================================
     FILE PARAMETER 
-      Extends channelType for parameters with input/output semantics and file extension
+      Extends multipleType for parameters with file extension
       information (file, image).
   ===================================================================
   -->
   <xsd:complexType name="fileType">
     <xsd:complexContent>
       <xsd:extension base="multipleType">
-        <xsd:attribute name="fileExtensions" type="xsd:string"/>
+        <xsd:attribute name="fileExtensions" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of allowed file extensions (e.g. "nrrd,mhd").</xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
       </xsd:extension>
     </xsd:complexContent>
   </xsd:complexType>
@@ -252,6 +436,9 @@
     <xsd:complexContent>
       <xsd:extension base="fileType">
         <xsd:attribute name="type">
+          <xsd:annotation>
+            <xsd:documentation>Optionally specifies the allowed image type.</xsd:documentation>
+          </xsd:annotation>
           <xsd:simpleType>
             <xsd:restriction base="xsd:string">
               <xsd:enumeration value="scalar"/>
@@ -280,10 +467,23 @@
   </xsd:simpleType>
 
   <xsd:complexType name="flagType">
+    <xsd:annotation>
+      <xsd:documentation>A single character flag (e.g. "s", "W", etc.). Not required if "longFlag" is specified.</xsd:documentation>
+    </xsd:annotation>
     <xsd:simpleContent>
       <xsd:extension base="flagValueType">
-        <xsd:attribute name="alias" type="xsd:string"/>
-        <xsd:attribute name="deprecatedalias" type="xsd:string"/>
+        <xsd:attribute name="alias" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of aliases. Can be used to provide different flags for the same parameter.
+            </xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
+        <xsd:attribute name="deprecatedalias" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of deprecated aliases. When invoking a module with one of these aliases,
+            the callee will be notified about the new preferred flag name.</xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
       </xsd:extension>
     </xsd:simpleContent>
   </xsd:complexType>
@@ -295,20 +495,51 @@
   </xsd:simpleType>
 
   <xsd:complexType name="longFlagType">
+    <xsd:annotation>
+      <xsd:documentation>A multi-character flag (e.g. "spacing", "Watcher", etc.). Not required if "flag" is specified.</xsd:documentation>
+    </xsd:annotation>
     <xsd:simpleContent>
       <xsd:extension base="longFlagValueType">
-        <xsd:attribute name="alias" type="xsd:string"/>
-        <xsd:attribute name="deprecatedalias" type="xsd:string"/>
+        <xsd:attribute name="alias" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of aliases. Can be used to provide different long flags for the same parameter.
+            </xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
+        <xsd:attribute name="deprecatedalias" type="xsd:string">
+          <xsd:annotation>
+            <xsd:documentation>A comma separated list of deprecated aliases. When invoking a module with one of these aliases,
+            the callee will be notified about the new preferred long flag name.
+            </xsd:documentation>
+          </xsd:annotation>
+        </xsd:attribute>
       </xsd:extension>
     </xsd:simpleContent>
   </xsd:complexType>
 
   <!-- constraints for scalar parameters (integer, double, float) -->
   <xsd:complexType name="constraintsType">
+    <xsd:annotation>
+      <xsd:documentation>Constraints on the allowed parameter value for scalar types and their vector variants.</xsd:documentation>
+    </xsd:annotation>
     <xsd:all>
-      <xsd:element minOccurs="0" name="minimum" type="xsd:double"/>
-      <xsd:element minOccurs="0" name="maximum" type="xsd:double"/>
-      <xsd:element name="step" type="xsd:double"/>
+      <xsd:element minOccurs="0" name="minimum" type="xsd:double">
+        <xsd:annotation>
+          <xsd:documentation>The minimum allowed value for the parameter. If not specified, the minimum is the smallest
+          possible value for the parameter type.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      <xsd:element minOccurs="0" name="maximum" type="xsd:double">
+        <xsd:annotation>
+          <xsd:documentation>The maximum allowed value for the parameter. If not specified, the maximum is the largest
+          possible value for the parameter type.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      <xsd:element name="step" type="xsd:double">
+        <xsd:annotation>
+          <xsd:documentation>The increment for the parameter.</xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
     </xsd:all>
   </xsd:complexType>
 

Libs/CommandLineModules/Core/ctkCmdLineModuleBackend.h

@@ -31,12 +31,17 @@ template<typename T> class QList;
 class QUrl;
 
 /**
- * \class ctkCmdLineModuleBackend
- * \brief Abstract base class for all back-end command line module
+ * @ingroup CommandLineModulesCore_API
+ *
+ * @brief Abstract base class for all back-end command line module
  * implementations.
- * \ingroup CommandLineModulesCore
- * \see ctkCmdLineModuleBackendLocalProcess
- * \see ctkCmdLineModuleBackendFunctionPointer
+ *
+ * A back-end is responsible for providing the XML module description for a
+ * given URL and its "timestamp". It also knows how to actually run a module,
+ * using the current parameter values provided by a ctkCmdLineModuleFrontend instance.
+ *
+ * @see ctkCmdLineModuleBackendLocalProcess
+ * @see ctkCmdLineModuleBackendFunctionPointer
  */
 struct CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleBackend
 {
@@ -57,8 +62,7 @@ struct CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleBackend
   virtual QString description() const = 0;
 
   /**
-   * @brief Returns a list of the capabilities or the types of things
-   * that this back-end can run.
+   * @brief Returns a list of URL schemes this back-end can handle.
    * @return A list of "schemes", meaning the capabilities.
    */
   virtual QList<QString> schemes() const = 0;
@@ -76,7 +80,9 @@ struct CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleBackend
    * @return The raw XML parameter description.
    *
    * This method may be concurrently called by the ctkCmdLineModuleManager and
-   * must be thread-safe.
+   * must be thread-safe. Implementations must not use any caching mechanism,
+   * as caching is done by the ctkCmdLineModuleManager itself, checking the
+   * return value of timeStamp().
    *
    */
   virtual QByteArray rawXmlDescription(const QUrl& location) = 0;
@@ -87,7 +93,11 @@ protected:
 
   /**
    * @brief The main method to actually execute the back-end process.
-   * @param A pointer to a front end implementation.
+   * @param frontend A pointer to a front end implementation.
+   *
+   * Implementations must execute the actual task of running the module asynchronously
+   * and return from this method immediately. After returning from this method,
+   * accessing the <code>frontend</code> pointer is not guaranteed to be safe.
    */
   virtual ctkCmdLineModuleFuture run(ctkCmdLineModuleFrontend* frontend) = 0;
 

Libs/CommandLineModules/Core/ctkCmdLineModuleCache_p.h

@@ -32,7 +32,7 @@ class QUrl;
  * \class ctkCmdLineModuleCache
  * \brief Private non-exported class to contain a cache of
  * XML descriptions and time-stamps.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  */
 class ctkCmdLineModuleCache
 {

Libs/CommandLineModules/Core/ctkCmdLineModuleConcurrentHelpers.h

@@ -29,7 +29,7 @@
 class ctkCmdLineModuleManager;
 
 /**
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  *
  * \brief A function object for concurrently adding modules.
  */
@@ -51,7 +51,7 @@ private:
 };
 
 /**
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  *
  * \brief A function object for concurrently removing modules.
  */

Libs/CommandLineModules/Core/ctkCmdLineModuleDefaultPathBuilder.h

@@ -31,7 +31,7 @@ struct ctkCmdLineModuleDefaultPathBuilderPrivate;
  * \class ctkCmdLineModuleDefaultPathBuilder
  * \brief Builds up a list of directory paths to search for command
  * line modules.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  * \author m.clarkson@ucl.ac.uk
  *
  * Implements the following basic strategy, depending on which boolean

Libs/CommandLineModules/Core/ctkCmdLineModuleDescription.h

@@ -37,7 +37,7 @@ class ctkCmdLineModuleParameter;
 /**
  * \class ctkCmdLineModuleDescription
  * \brief Description of the parameters of a command line module.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  *
  * The parameters can be used for automated GUI generation or execution
  * of the module, and are directly related to the XML description used to

Libs/CommandLineModules/Core/ctkCmdLineModuleDirectoryWatcher.h

@@ -35,7 +35,7 @@ class ctkCmdLineModuleDirectoryWatcherPrivate;
  * \class ctkCmdLineModuleDirectoryWatcher
  * \brief Provides directory scanning to automatically load new modules
  * into a ctkCmdLineModuleManager.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  * \author m.clarkson@ucl.ac.uk
  *
  * This class provides directory scanning and automatic loading of command

Libs/CommandLineModules/Core/ctkCmdLineModuleDirectoryWatcher_p.h

@@ -34,7 +34,7 @@ class QFileSystemWatcher;
 /**
  * \class ctkCmdLineModuleDirectoryWatcherPrivate
  * \brief Private implementation class implementing directory scanning to load new modules into a ctkCmdLineModuleManager.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  * \author m.clarkson@ucl.ac.uk
  */
 class ctkCmdLineModuleDirectoryWatcherPrivate : public QObject

Libs/CommandLineModules/Core/ctkCmdLineModuleFrontend.h

@@ -39,7 +39,13 @@ struct ctkCmdLineModuleFrontendPrivate;
  * \class ctkCmdLineModuleFrontend
  * \brief Abstract base class for all front-end command
  * line module implementations.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
+ *
+ * A module front-end represents a set of current parameter values for a specific
+ * module. A front-end instance is usually associated with a graphical user interface,
+ * accessible via guiHandle(). This allows users to interactively change parameter values
+ * of the module.
+ *
  * \see ctkCmdLineModuleFrontendQtGui
  * \see ctkCmdLineModuleFrontendQtWebKit
  */
@@ -85,8 +91,11 @@ public:
   };
 
   enum ParameterFilter {
+    /** Parameters with channel = "input" */
     Input = 0x01,
+    /** Parameter with channel = "output" */
     Output = 0x02,
+    /** A convenience enum value combining Input and Output. */
     All = Input | Output
   };
   Q_DECLARE_FLAGS(ParameterFilters, ParameterFilter)
@@ -94,10 +103,13 @@ public:
   ~ctkCmdLineModuleFrontend();
 
   /**
-   * @brief Returns the GUI representation, currently supporting only
-   * QObject subclasses.
-   * @return The GUI that can then be embeded in an applicaiton
-   * window for instance.
+   * @brief Returns the GUI representation.
+   * @return A GUI handle that can then be embeded in an application window for instance.
+   *
+   * The returned object is a handle to the real GUI toolkit specific object representing
+   * the user interface. For Qt based front-ends, the returned object is usually a QWidget
+   * instance pointing to the main container widget for the GUI. See the documentation
+   * of the front-end sub-class for specific information.
    */
   virtual QObject* guiHandle() const = 0;
 
@@ -169,14 +181,16 @@ public:
   virtual void setValues(const QHash<QString,QVariant>& values);
 
   /**
-   * @brief Indicates if the underlying process is currently active.
-   * @return true if running and false otherwise.
+   * @brief Indicates if the currently associated ctkCmdLineModuleFuture object
+   *        is in state "running".
+   * @return \c true if running and \c false otherwise.
    */
   bool isRunning() const;
 
   /**
-   * @brief Indicates if the underlying process is currently paused.
-   * @return true if paused and false otherwise.
+   * @brief Indicates if the currently associated ctkCmdLineModuleFuture Object
+   *        is in state "paused".
+   * @return \c true if paused and \c false otherwise.
    */
   bool isPaused() const;
 
@@ -200,7 +214,7 @@ Q_SIGNALS:
 
   /**
    * @brief This signal is emitted whenever a parameter value is changed by using
-   *        the ctkCmdLineModuleFrontent class.
+   *        the ctkCmdLineModuleFrontend class.
    * @param parameter The parameter name.
    * @param value The new parameter value.
    *
@@ -224,12 +238,6 @@ protected:
    */
   ctkCmdLineModuleFrontend(const ctkCmdLineModuleReference& moduleRef);
 
-  /**
-   * @brief Sets the ctkCmdLineModuleFuture which effectively
-   * contains the backend that is run.
-   */
-  void setFuture(const ctkCmdLineModuleFuture& future);
-
 private Q_SLOTS:
 
   /**
@@ -244,6 +252,14 @@ private Q_SLOTS:
 
 private:
 
+  /**
+   * @brief Sets the ctkCmdLineModuleFuture which effectively
+   * contains the backend that is run.
+   */
+  void setFuture(const ctkCmdLineModuleFuture& future);
+
+private:
+
   Q_DISABLE_COPY(ctkCmdLineModuleFrontend)
 
   friend struct ctkCmdLineModuleFrontendPrivate;

Libs/CommandLineModules/Core/ctkCmdLineModuleFrontendFactory.h

@@ -30,16 +30,34 @@ class ctkCmdLineModuleReference;
 /**
  * \class ctkCmdLineModuleFrontendFactory
  * \brief Factory class to create new front-ends.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
+ *
+ * Front-end implementors are advised to create and export a sub-class of
+ * this class to unify the creation process of front-ends.
+ *
  * \see ctkCmdLineModuleFrontend
  */
 struct CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleFrontendFactory
 {
   virtual ~ctkCmdLineModuleFrontendFactory();
 
+  /**
+   * @brief Get the name of this factory.
+   * @return The factory name.
+   */
   virtual QString name() const = 0;
+
+  /**
+   * @brief Get the description for this factory.
+   * @return A factory description.
+   */
   virtual QString description() const = 0;
 
+  /**
+   * @brief Creates front-end instances.
+   * @param moduleRef The module reference for which to create a front-end.
+   * @return The created front-end or NULL if creation failed.
+   */
   virtual ctkCmdLineModuleFrontend* create(const ctkCmdLineModuleReference& moduleRef) = 0;
 };
 

Libs/CommandLineModules/Core/ctkCmdLineModuleFuture.h

@@ -30,14 +30,15 @@
 
 /**
  * \class ctkCmdLineModuleFuture
- * \brief QFuture sub-class with in addition canCancel() and canPause().
- * \ingroup CommandLineModulesCore
+ * \brief QFuture sub-class for enhanced communication with running modules.
+ * \ingroup CommandLineModulesCore_API
  *
+ * Please see the QFuture documentation of Qt for details. This sub-class provides
+ * additional query methods to check if a module can be paused and/or canceled and
+ * also provides the ability to retrieve the arbitrary output and error data
+ * from the module.
  *
- * QFuture sub-class with two additional methods:
- *
- *   - bool canCancel()
- *   - bool canPause()
+ * \see ctkCmdLineModuleFutureWatcher
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleFuture : public QFuture<ctkCmdLineModuleResult>
 {
@@ -45,12 +46,32 @@ public:
 
   ctkCmdLineModuleFuture();
 
+  /** \cond */
   explicit ctkCmdLineModuleFuture(ctkCmdLineModuleFutureInterface* p); // internal
+  /** \endcond */
 
+  /**
+   * @brief Read all output data reported by the running module so far.
+   * @return Returns the reported output.
+   */
   QByteArray readAllOutputData() const;
+
+  /**
+   * @brief Read all error data reported by the running module so far.
+   * @return Returns the reported error.
+   */
   QByteArray readAllErrorData() const;
 
+  /**
+   * @brief Check if this module can be canceled via cancel().
+   * @return \c true if this module can be canceled, \c false otherwise.
+   */
   bool canCancel() const;
+
+  /**
+   * @brief Check if this module can be paused via pause() and similar QFuture methods.
+   * @return \c true if this module can be paused, \c false otherwise.
+   */
   bool canPause() const;
 
 };

Libs/CommandLineModules/Core/ctkCmdLineModuleFutureInterface.h

@@ -32,7 +32,7 @@ class ctkCmdLineModuleFuture;
 class ctkCmdLineModuleFutureInterfacePrivate;
 
 /**
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  *
  * \brief A QFutureInterface specialization.
  *

Libs/CommandLineModules/Core/ctkCmdLineModuleFutureWatcher.h

@@ -33,6 +33,8 @@ class ctkCmdLineModuleFuture;
 struct ctkCmdLineModuleFutureWatcherPrivate;
 
 /**
+ * @ingroup CommandLineModulesCore_API
+ *
  * @brief The ctkCmdLineModuleFutureWatcher class provides enhanced monitoring of a
  *        ctkCmdLineModuleFuture using signals and slots.
  *

Libs/CommandLineModules/Core/ctkCmdLineModuleManager.h

@@ -36,9 +36,35 @@ class ctkCmdLineModuleFuture;
 struct ctkCmdLineModuleManagerPrivate;
 
 /**
- * \class ctkCmdLineModuleManager
- * \brief Main manager class to handle loading and unloading of modules.
- * \ingroup CommandLineModulesCore
+ * @ingroup CommandLineModulesCore_API
+ *
+ * @brief Main manager class to handle loading and unloading of modules.
+ *
+ * This is the central managing class for CTK "command line modules". To register modules,
+ * you need a command line module back-end which is capable of handling the URL scheme
+ * under which you want to register your modules.
+ *
+ * A default back-end for handling "file" URLs which runs local executables is
+ * available in ctkCmdLineModuleBackendLocalProcess.
+ *
+ * To create and run a specific front-end for a given module, you need a concrete
+ * ctkCmdLineModuleFrontend implementation. The implementation provided in
+ * ctkCmdLineModuleFrontendQtGui creates a default Qt widgets based GUI for a given
+ * ctkCmdLineModuleReference instance.
+ *
+ * Here is an example how this and related classes could be used:
+ *
+ * First, we create ctkCmdLineModuleManager instance.
+ * \snippet ModuleManager/main.cpp instantiate-mm
+ *
+ * Then we need at least one back-end which can handle registering modules.
+ * \snippet ModuleManager/main.cpp register-backend
+ *
+ * Finally, we can register a module.
+ * \snippet ModuleManager/main.cpp register-module
+ *
+ * @see ctkCmdLineModuleFrontend
+ * @see ctkCmdLineModuleBackend
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleManager : public QObject
 {
@@ -58,23 +84,86 @@ public:
     WEAK_VALIDATION
   };
 
-  ctkCmdLineModuleManager(ValidationMode = STRICT_VALIDATION, const QString& cacheDir = QString());
+  /**
+   * @brief Create a module manager instance.
+   * @param validationMode The validation mode for the XML description of the module parameters.
+   * @param cacheDir The directory where to cache information about registered modules.
+   *
+   * If the <code>validationMode</code> argument is set to <code>SKIP_VALIDATION</code>, no XML validation
+   * takes place and certain front-ends might fail to generate a GUI. If it is set to
+   * <code>WEAK_VALIDATION</code>, module registrations will proceed on error but the error status
+   * is available via ctkCmdLineModuleReference::xmlValidationErrorString().
+   */
+  ctkCmdLineModuleManager(ValidationMode validationMode = STRICT_VALIDATION,
+                          const QString& cacheDir = QString());
 
   ~ctkCmdLineModuleManager();
 
+  /**
+   * @brief Registers a new back-end.
+   * @param backend The new back-end.
+   * @throws ctkInvalidArgumentException if another back-end was already registered handling
+   *         one of the URL schemes this back-end claims to handle.
+   */
   void registerBackend(ctkCmdLineModuleBackend* backend);
 
+  /**
+   * @brief Registers a module, identified by the give URL.
+   * @param location The URL for the new module.
+   * @return A module reference.
+   * @throws ctkInvalidArgumentException if no back-end for the given URL scheme was registered
+   *         or the XML description for the module is invalid.
+   */
   ctkCmdLineModuleReference registerModule(const QUrl& location);
+
+  /**
+   * @brief Unregister a previously registered module.
+   * @param moduleRef The reference for the module to unregister.
+   *
+   * This method does nothing if the module reference <code>moduleRef</code> is invalid or
+   * reference an un-registered module.
+   */
   void unregisterModule(const ctkCmdLineModuleReference& moduleRef);
 
+  /**
+   * @brief Returns a ctkCmdLineModuleReference object for the given URL.
+   * @param location The location URL for which to get a module reference.
+   * @return The module reference for the location or an invalid module reference
+   *         if no module was registered under the given location URL.
+   */
   ctkCmdLineModuleReference moduleReference(const QUrl& location) const;
+
+  /**
+   * @brief Returns module references for all currently registered modules.
+   * @return A list of module references.
+   */
   QList<ctkCmdLineModuleReference> moduleReferences() const;
 
+  /**
+   * @brief Run a module front-end.
+   * @param frontend The module front-end to run.
+   * @return A ctkCmdLineModuleFuture object which can be used to interact with the
+   *         running front-end.
+   *
+   * This method takes a ctkCmdLineModuleFrontend pointer and uses the registered back-end
+   * for this module's location URL scheme to run it asynchronously. The returned future object
+   * is the only way to interact with the task started by the specific back-end.
+   *
+   * @see ctkCmdLineModuleFuture
+   * @see ctkCmdLineModuleFutureWatcher
+   */
   ctkCmdLineModuleFuture run(ctkCmdLineModuleFrontend* frontend);
 
 Q_SIGNALS:
 
+  /**
+   * @brief This signal is emitted whenever a module is registered.
+   */
   void moduleRegistered(const ctkCmdLineModuleReference&);
+
+  /**
+   * @brief This signal is emitted whenever a module is un-registered.
+   */
   void moduleUnregistered(const ctkCmdLineModuleReference&);
 
 private:

Libs/CommandLineModules/Core/ctkCmdLineModuleParameter.h

@@ -33,7 +33,7 @@ struct ctkCmdLineModuleParameterPrivate;
 /** 
  * \class ctkCmdLineModuleParameter
  * \brief Single parameter to a module, like a threshold of a filter.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  *
  *
  * ctkCmdLineModuleParameter describes a single parameter for a

Libs/CommandLineModules/Core/ctkCmdLineModuleParameterGroup.h

@@ -34,7 +34,7 @@ struct ctkCmdLineModuleParameterGroupPrivate;
 /** 
  * \class ctkCmdLineModuleParameterGroup
  * \brief Group of parameters
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleParameterGroup
 {

Libs/CommandLineModules/Core/ctkCmdLineModuleReference.h

@@ -34,29 +34,60 @@ struct ctkCmdLineModuleReferencePrivate;
 /**
  * \class ctkCmdLineModuleReference
  * \brief Defines a reference or handle to a module, including location,
- * XML, description and access to the backend.
- * \ingroup CommandLineModulesCore
+ * XML, description and access to the associated backend.
+ * \ingroup CommandLineModulesCore_API
+ *
+ * Instances of this class reference registered modules and can be used
+ * to retrieve information about their parameters or to create a specific
+ * front-end.
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleReference
 {
 public:
 
+  /**
+   * @brief Creates an invalid module reference.
+   */
   ctkCmdLineModuleReference();
   ~ctkCmdLineModuleReference();
 
   ctkCmdLineModuleReference(const ctkCmdLineModuleReference& ref);
   ctkCmdLineModuleReference& operator=(const ctkCmdLineModuleReference& ref);
 
+  /**
+   * @brief Conversion operator to test the validity of this module reference.
+   */
   operator bool() const;
 
+  /**
+   * @brief Get the module description for the parameters.
+   * @return The XML description as a class representation.
+   */
   ctkCmdLineModuleDescription description() const;
 
+  /**
+   * @brief Get the raw XML description, as supplied by the back-end.
+   * @return The raw XML description.
+   */
   QByteArray rawXmlDescription() const;
 
+  /**
+   * @brief Retrieve a validation error string.
+   * @return A non-empty string describing the validation error, if validation
+   *         of the XML description was not successful.
+   */
   QString xmlValidationErrorString() const;
 
+  /**
+   * @brief Get the URL under which the module was registered.
+   * @return The module location.
+   */
   QUrl location() const;
 
+  /**
+   * @brief Get the back-end which was registered to handle this module.
+   * @return The back-end handling this module.
+   */
   ctkCmdLineModuleBackend* backend() const;
 
 private:

Libs/CommandLineModules/Core/ctkCmdLineModuleResult.h

@@ -26,9 +26,15 @@
 #include <QVariant>
 
 /**
- * \class ctkCmdLineModuleResult
- * \brief Describes the output of a command line module.
- * \ingroup CommandLineModulesCore
+ * @ingroup CommandLineModulesCore_API
+ *
+ * @brief Describes a reported result of a command line module.
+ *
+ * This class wraps a specific result reported by a running module via a
+ * ctkCmdLineModuleFuture instance.
+ *
+ * @see ctkCmdLineModuleFuture
+ * @see ctkCmdLineModuleFutureWatcher
  */
 class ctkCmdLineModuleResult
 {
@@ -45,8 +51,17 @@ public:
     return Parameter == other.Parameter && Value == other.Value;
   }
 
-  inline QString parameter() const { return Parameter; }
-  inline QVariant value() const { return Value; }
+  /**
+   * @brief Get the name of the output parameter for which this result was reported.
+   * @return The output parameter name.
+   */
+  QString parameter() const;
+
+  /**
+   * @brief Get the result value.
+   * @return The result value.
+   */
+  QVariant value() const;
 
 private:
 

Libs/CommandLineModules/Core/ctkCmdLineModuleRunException.h

@@ -31,7 +31,7 @@
 /**
  * \class ctkCmdLineModuleRunException
  * \brief Exception class to describe problems with running the module.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleRunException
     : public QtConcurrent::Exception, public ctkException

Libs/CommandLineModules/Core/ctkCmdLineModuleXmlException.h

@@ -29,7 +29,7 @@
 /**
  * \class ctkCmdLineModuleXmlException
  * \brief Exception class to describe problems with XML processing.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  */
 CTK_DECLARE_EXCEPTION(CTK_CMDLINEMODULECORE_EXPORT, ctkCmdLineModuleXmlException, ctkException)
 

Libs/CommandLineModules/Core/ctkCmdLineModuleXmlMsgHandler_p.h

@@ -27,7 +27,7 @@
 /**
  * \class QAbstractMessageHandler
  * \brief Class to handle an XML message.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  */
 class ctkCmdLineModuleXmlMsgHandler : public QAbstractMessageHandler
 {

Libs/CommandLineModules/Core/ctkCmdLineModuleXmlParser_p.h

@@ -34,7 +34,7 @@ class QIODevice;
 /**
  * \class ctkCmdLineModuleXmlParser
  * \brief Performs XML parsing, loading data into a ctkCmdLineModuleDescription
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
  * \see ctkCmdLineModuleDescription
  */
 class ctkCmdLineModuleXmlParser

Libs/CommandLineModules/Core/ctkCmdLineModuleXmlProgressWatcher.h

@@ -34,7 +34,11 @@ class QProcess;
 /**
  * \class ctkCmdLineModuleXmlProgressWatcher
  * \brief Provides progress updates of a module.
- * \ingroup CommandLineModulesCore
+ * \ingroup CommandLineModulesCore_API
+ *
+ * This class is usually only used by back-end implementators for modules
+ * which can report progress and results in the form of XML fragments written
+ * to a QIODevice.
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleXmlProgressWatcher : public QObject
 {

Libs/CommandLineModules/Core/ctkCmdLineModuleXmlValidator.h

@@ -31,9 +31,10 @@ class ctkCmdLineModuleXmlValidatorPrivate;
 class QIODevice;
 
 /**
- * \class ctkCmdLineModuleXmlValidator
- * \brief Provides XML validation, comparing a modules XML to an .xsd file
- * \ingroup CommandLineModulesCore
+ * @ingroup CommandLineModulesCore_API
+ *
+ * @brief Provides validation of an XML document against an XML schema.
+ *
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleXmlValidator
 {
@@ -43,14 +44,40 @@ public:
   ctkCmdLineModuleXmlValidator(QIODevice* input = 0);
   ~ctkCmdLineModuleXmlValidator();
 
+  /**
+   * @brief Set the XML input.
+   * @param input The Xml input.
+   */
   void setInput(QIODevice* input);
+
+  /**
+   * @brief Get the XML input device.
+   * @return The XML input device.
+   */
   QIODevice* input() const;
 
+  /**
+   * @brief Set the XML schema to be used during validation.
+   * @param input The XML schema.
+   */
   void setInputSchema(QIODevice* input);
 
+  /**
+   * @brief Validate the XML input against the XML schema set via setInputSchema().
+   * @return \c true if validation was successful, \c false otherwise.
+   */
   virtual bool validateInput();
 
+  /**
+   * @brief Get the error flag.
+   * @return \c true if an error occured during validation, \c false otherwise.
+   */
   virtual bool error() const;
+
+  /**
+   * @brief Get the error string.
+   * @return A description of the validation error, if any.
+   */
   virtual QString errorString() const;
 
 private:

Libs/CommandLineModules/Core/ctkCmdLineModuleXslTransform.cpp

@@ -280,6 +280,12 @@ void ctkCmdLineModuleXslTransform::setValidateOutput(bool validate)
 }
 
 //----------------------------------------------------------------------------
+bool ctkCmdLineModuleXslTransform::validateOutput() const
+{
+  return d->Validate;
+}
+
+//----------------------------------------------------------------------------
 bool ctkCmdLineModuleXslTransform::error() const
 {
   return ctkCmdLineModuleXmlValidator::error() || !d->ErrorStr.isEmpty();

Libs/CommandLineModules/Core/ctkCmdLineModuleXslTransform.h

@@ -31,9 +31,14 @@ class ctkCmdLineModuleXslTransformPrivate;
 class QIODevice;
 
 /**
- * \class ctkCmdLineModuleXslTransform
- * \brief Provides a transformation from XML to the Qt ui file format.
- * \ingroup CommandLineModulesCore
+ * @ingroup CommandLineModulesCore_API
+ *
+ * @brief Transforms a given XML input using an XML stylesheet.
+ *
+ * You must call setInput(), setOutput() and setXslTransformation() before
+ * calling transform().
+ *
+ * @see ctkCmdLineModuleXmlValidator
  */
 class CTK_CMDLINEMODULECORE_EXPORT ctkCmdLineModuleXslTransform
   : public ctkCmdLineModuleXmlValidator
@@ -44,14 +49,31 @@ public:
   ctkCmdLineModuleXslTransform(QIODevice* input = 0, QIODevice* output = 0);
   virtual ~ctkCmdLineModuleXslTransform();
 
+  /**
+   * @brief Set the output device to which the transformation will be written.
+   * @param output The output device.
+   *
+   * If no output device is set, a default device will be used.
+   */
   void setOutput(QIODevice* output);
+
+  /**
+   * @brief Get the output device to which the transformation will be written.
+   * @return The output device.
+   */
   QIODevice* output() const;
 
+  /**
+   * @brief Set an XML schema for output validation.
+   * @param output The XML schema against which the transformation will be validated.
+   *
+   * Output validation will only be done if validateOutput() returns \c true.
+   */
   void setOutputSchema(QIODevice* output);
 
   /**
-   * @brief Returns \code true if the XSL output will be formatted.
-   * @return \code true if the ouptut will be formatted, \code false otherwise.
+   * @brief Returns \c true if the XSL output will be formatted.
+   * @return \c true if the ouptut will be formatted, \c false otherwise.
    */
   bool formatXmlOutput() const;
 
@@ -60,7 +82,7 @@ public:
    *
    * It is assumed that the XSL output is valid XML. The output will be
    * formatted with an indentation depth of four spaces. Note that setting
-   * \e format to \code true increases compuational overhead and memory
+   * \c format to \c true increases compuational overhead and memory
    * requirements and is usually only done for testing or debugging purposes.
    */
   void setFormatXmlOutput(bool format);
@@ -69,7 +91,8 @@ public:
    * @brief Transforms an XML input via a XSL transformation.
    *
    * This method assumes that the input set via setInput() or supplied
-   * in the constructor is a valid, non empty XML fragment.
+   * in the constructor is a valid, non empty XML fragment and that setOutput()
+   * and setXslTransformation() was called with non-null arguments.
    *
    * @return
    */
@@ -82,7 +105,7 @@ public:
    * to transform the input without setting a transformation will result in
    * runtime errors.
    *
-   * @param The XSL transformation.
+   * @param transformation The XSL transformation.
    */
   void setXslTransformation(QIODevice* transformation);
 
@@ -106,19 +129,37 @@ public:
    */
   void bindVariable(const QString& name, const QVariant& value);
 
+  /**
+   * @brief Sets the output validation mode.
+   * @param validate If \c true, the output will be validated against the XML schema
+   *        provided via setOutputSchema(). If \c validate is \c false, no output
+   *        validation takes place.
+   */
   void setValidateOutput(bool validate);
 
-  /** @brief returns true if an error occured
-   *  transform() sets the error flag if an error occured when transforming the
-   *  XML file into XSL.
-   *  \sa errorString
+  /**
+   * @brief Get the output validation mode.
+   * @return \c true if the output will be validated, \c false otherwise.
+   */
+  bool validateOutput() const;
+
+  /**
+   * @brief Returns true if an error occured.
+   *
+   * transform() sets the error flag if an error occured when transforming the
+   * XML file into XSL or validating the transformation.
+   *
+   * @sa errorString
    */
   virtual bool error() const;
 
-  /** @brief Error message if any
-   *  transform() sets the error message if an error occured when transforming
+  /**
+   * @brief Returns the error message if any.
+   *
+   * transform() sets the error message if an error occured when transforming
    * the XML file into XSL.
-   *  \sa error
+   *
+   * @sa error
    */
   virtual QString errorString() const;
 

Libs/CommandLineModules/Documentation/Backends.md

@@ -0,0 +1,7 @@
+Backends    {#CommandLineModulesBackEnds_Page}
+========
+
+Here is a list of available back-ends:
+
+- \subpage CommandLineModulesBackendFunctionPointer_Page
+- \subpage CommandLineModulesBackendLocalProcess_Page

Libs/CommandLineModules/Documentation/CMakeLists.txt

@@ -0,0 +1,12 @@
+
+# Copy the xs3p.xsl stylesheet which is used in .xsd files to generate nice
+# html output when opened in a browser.
+execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/xs3p.xsl
+                                                              ${CTK_BINARY_DIR}/Documentation/html/xs3p.xsl)
+
+if (BUILD_TESTING AND
+    CTK_LIB_CommandLineModules/Core AND CTK_LIB_CommandLineModules/Backend/LocalProcess)
+  
+  # Compile source code snippets
+  add_subdirectory(Snippets)
+endif()

Libs/CommandLineModules/Documentation/CTKCommandLineModules.dox

@@ -1,34 +1,54 @@
 /**
 
-\defgroup CommandLineModules Command Line Modules
+\defgroup CommandLineModules_Group Command Line Modules
 \ingroup Projects
 
-CTK provides an API for interfacing with command line modules through a
-self-describing XML description of the supported command line arguments.
+See the sub-modules for detailed API documentation of the available front and back-ends.
 
-\defgroup CommandLineModulesCore Command Line Module Core
+For a high-level overview, see \ref CommandLineModules_Page.
+
+\defgroup CommandLineModulesCore_API Command Line Module Core API
 \ingroup Libs
-\ingroup CommandLineModules
+\ingroup CommandLineModules_Group
+
+This is a list of types provided by the CTK Command Line Module Core library. See the
+\ref CommandLineModulesCore_Page library page for general information.
 
-\defgroup CommandLineModulesBackEnd Command Line Module Back-End
+\defgroup CommandLineModulesBackEnd_Group Command Line Module Back-Ends
 \ingroup Libs
-\ingroup CommandLineModules
+\ingroup CommandLineModules_Group
+
+This module groups back-end implementations. See ctkCmdLineModuleBackend for details about back-ends.
+
+\defgroup CommandLineModulesBackendFunctionPointer_API Function Pointer API (experimental)
+\ingroup CommandLineModulesBackEnd_Group
 
-\defgroup CommandLineModulesBackendFunctionPointer Command Line Module Function Pointer
-\ingroup CommandLineModulesBackEnd
+This is a list of types provided by the CTK Command Line Module Function Pointer Backend library. See the
+\ref CommandLineModulesBackendFunctionPointer_Page library page for general information.
 
-\defgroup CommandLineModulesBackendLocalProcess Command Line Module Local Process
-\ingroup CommandLineModulesBackEnd
+\defgroup CommandLineModulesBackendLocalProcess_API Local Process API
+\ingroup CommandLineModulesBackEnd_Group
 
-\defgroup CommandLineModulesFrontEnd Command Line Module Front-End
+This is a list of types provided by the CTK Command Line Module Local Process Backend library. See the
+\ref CommandLineModulesBackendLocalProcess_Page library page for general information.
+
+\defgroup CommandLineModulesFrontEnd_Group Command Line Module Front-Ends
 \ingroup Libs
-\ingroup CommandLineModules
+\ingroup CommandLineModules_Group
+
+This module groups front-end implementations. See ctkCmdLineModuleFrontend for details about front-ends.
+
+\defgroup CommandLineModulesFrontendQtGui_API QtGui API
+\ingroup CommandLineModulesFrontEnd_Group
+
+This is a list of types provided by the CTK Command Line Module Qt Gui Frontend library. See the
+\ref CommandLineModulesFrontendQtGui_Page library page for general information.
 
-\defgroup CommandLineModulesFrontendQtGui Command Line Module QtGui
-\ingroup CommandLineModulesFrontEnd
+\defgroup CommandLineModulesFrontendQtWebKit_API QtWebKit API (experimental)
+\ingroup CommandLineModulesFrontEnd_Group
 
-\defgroup CommandLineModulesFrontendQtWebKit Command Line Module QtWebKit
-\ingroup CommandLineModulesFrontEnd
+This is a list of types provided by the CTK Command Line Module Qt WebKit Frontend library. See the
+\ref CommandLineModulesFrontendQtWebKit_Page library page for general information.
 
 */
 

Libs/CommandLineModules/Documentation/Frontends.md

@@ -0,0 +1,7 @@
+Frontends    {#CommandLineModulesFrontEnds_Page}
+=========
+
+Here is a list of available front-ends:
+
+- \subpage CommandLineModulesFrontendQtGui_Page
+- \subpage CommandLineModulesFrontendQtWebKit_Page

Libs/CommandLineModules/Documentation/Snippets/CMakeLists.txt

@@ -0,0 +1,19 @@
+
+set(_base_src_include_dir ${CMAKE_SOURCE_DIR}/Libs/CommandLineModules)
+set(_base_bin_include_dir ${CMAKE_BINARY_DIR}/Libs/CommandLineModules)
+
+include_directories(
+  ${CTKCore_SOURCE_DIR}
+  ${CTKCore_BINARY_DIR}
+  ${_base_src_include_dir}/Core
+  ${_base_bin_include_dir}/Core
+  ${_base_src_include_dir}/Backend/LocalProcess
+  ${_base_bin_include_dir}/Backend/LocalProcess
+  ${_base_src_include_dir}/Frontend/QtGui
+  ${_base_bin_include_dir}/Frontend/QtGui
+)
+
+ctkFunctionCompileSnippets("${CMAKE_CURRENT_SOURCE_DIR}"
+  CTKCommandLineModulesBackendLocalProcess
+  CTKCommandLineModulesFrontendQtGui
+)

Libs/CommandLineModules/Documentation/Snippets/ModuleManager/main.cpp

@@ -0,0 +1,112 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) German Cancer Research Center,
+    Division of Medical and Biological Informatics
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+=============================================================================*/
+
+#include "ctkCmdLineModuleManager.h"
+#include "ctkCmdLineModuleBackendLocalProcess.h"
+#include "ctkCmdLineModuleFrontendFactoryQtGui.h"
+#include "ctkCmdLineModuleFrontendQtGui.h"
+#include "ctkCmdLineModuleFuture.h"
+#include "ctkException.h"
+#include "ctkCmdLineModuleRunException.h"
+
+#include <QApplication>
+#include <QDesktopServices>
+#include <QWidget>
+#include <QUrl>
+#include <QDebug>
+
+#include <cstdlib>
+
+int main(int argc, char** argv)
+{
+  QApplication myApp(argc, argv);
+  myApp.setOrganizationName("CommonTK");
+  myApp.setApplicationName("ModuleManagerSnippet");
+
+  // [instantiate-mm]
+  // Instantiate a ctkCmdLineModuleManager class.
+  ctkCmdLineModuleManager moduleManager(
+        // Use "strict" validation mode, rejecting modules with non-valid XML descriptions.
+        ctkCmdLineModuleManager::STRICT_VALIDATION,
+        // Use the default cache location for this application
+        QDesktopServices::storageLocation(QDesktopServices::CacheLocation)
+        );
+  // [instantiate-mm]
+
+  // [register-backend]
+  // Instantiate a back-end for running executable modules in a local process.
+  // This back-end handles the "file" Url scheme.
+  QScopedPointer<ctkCmdLineModuleBackend> processBackend(new ctkCmdLineModuleBackendLocalProcess);
+
+  // Register the back-end with the module manager.
+  moduleManager.registerBackend(processBackend.data());
+  // [register-backend]
+
+  // [register-module]
+  ctkCmdLineModuleReference moduleRef;
+  try
+  {
+    // Register a local executable as a module, the ctkCmdLineModuleBackendLocalProcess
+    // can handle it.
+    moduleRef = moduleManager.registerModule(QUrl::fromLocalFile("C:/modules/MyModule.exe"));
+  }
+  catch (const ctkInvalidArgumentException& e)
+  {
+    // Module validation failed.
+    qDebug() << e;
+    return EXIT_FAILURE;
+  }
+  // [register-module]
+
+  // [create-frontend]
+  // We use the "Qt Gui" frontend factory.
+  QScopedPointer<ctkCmdLineModuleFrontendFactory> frontendFactory(new ctkCmdLineModuleFrontendFactoryQtGui);
+  myApp.addLibraryPath(QCoreApplication::applicationDirPath() + "/../");
+
+  QScopedPointer<ctkCmdLineModuleFrontend> frontend(frontendFactory->create(moduleRef));
+
+  // Create the actual GUI representation.
+  QWidget* gui = qobject_cast<QWidget*>(frontend->guiHandle());
+  // [create-frontend]
+  Q_UNUSED(gui);
+
+  // Now try and run the module (using the default values for the parameters)
+  // and print out any reported output and results.
+  // [run-module]
+  try
+  {
+    ctkCmdLineModuleFuture future = moduleManager.run(frontend.data());
+    future.waitForFinished();
+    qDebug() << "Console output:";
+    qDebug() << future.readAllOutputData();
+    qDebug() << "Error output:";
+    qDebug() << future.readAllErrorData();
+    qDebug() << "Results:";
+    qDebug() << future.results();
+  }
+  catch (const ctkCmdLineModuleRunException& e)
+  {
+    qWarning() << e;
+  }
+  // [run-module]
+
+  return EXIT_SUCCESS;
+}

Libs/CommandLineModules/Frontend/QtGui/README.md

@@ -0,0 +1,8 @@
+Qt Gui Frontend    {#CommandLineModulesFrontendQtGui_Page}
+===============
+
+The Qt Gui front-end uses a customizable XML stylesheet to transform the raw XML module
+description into Qt .ui file. For details about the configuration possibilities of the GUI
+generation process see the ctkCmdLineModuleFrontendQtGui class.
+
+See the \ref CommandLineModulesFrontendQtGui_API module for the API documentation.

Libs/CommandLineModules/Frontend/QtGui/Resources/ctkCmdLineModuleXmlToQtUi.xsl

@@ -16,6 +16,17 @@
   ===================================================================
   -->
   
+  <!--
+  ########################################################################
+  ****************************   IMPORTANT   *****************************
+  *                                                                      *
+  * Please update the documentation in ctkCmdLineModuleFrontendQtGui.h   *
+  * when making changes to (or adding/removing) XSL parameters (names    *
+  * or default values)                                                   *
+  *                                                                      *
+  ########################################################################
+  -->
+  
   <xsl:param name="disableReturnParameter">true</xsl:param>
   
   <xsl:param name="executableWidget">QWidget</xsl:param>
@@ -42,15 +53,9 @@
   <xsl:param name="fileValueProperty">currentPath</xsl:param>
   <xsl:param name="directoryValueProperty">currentPath</xsl:param>
   <xsl:param name="geometryValueProperty">currentPath</xsl:param>
-  <xsl:param name="integervectorValueProperty">text</xsl:param>
-  <xsl:param name="doublevectorValueProperty">text</xsl:param>
-  <xsl:param name="floatvectorValueProperty">text</xsl:param>
-  <xsl:param name="stringvectorValueProperty">text</xsl:param>
-  <xsl:param name="integerenumerationValueProperty">currentEnumeration</xsl:param>
-  <xsl:param name="doubleenumerationValueProperty">currentEnumeration</xsl:param>
-  <xsl:param name="floatenumerationValueProperty">currentEnumeration</xsl:param>
-  <xsl:param name="stringenumerationValueProperty">currentEnumeration</xsl:param>
-  
+  <xsl:param name="vectorValueProperty">text</xsl:param>
+  <xsl:param name="enumerationValueProperty">currentEnumeration</xsl:param>
+
   
   <!--
   ===================================================================
@@ -79,20 +84,21 @@
       <xsl:when test="$cliType='boolean'"><xsl:value-of select="$booleanValueProperty"/></xsl:when>
       <xsl:when test="$cliType='integer'"><xsl:value-of select="$integerValueProperty"/></xsl:when>
       <xsl:when test="$cliType='float'"><xsl:value-of select="$floatValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='double'"><xsl:value-of select="$floatValueProperty"/></xsl:when>
       <xsl:when test="$cliType='point'"><xsl:value-of select="$pointValueProperty"/></xsl:when>
       <xsl:when test="$cliType='region'"><xsl:value-of select="$regionValueProperty"/></xsl:when>
       <xsl:when test="$cliType='image'"><xsl:value-of select="$imageValueProperty"/></xsl:when>
       <xsl:when test="$cliType='file'"><xsl:value-of select="$fileValueProperty"/></xsl:when>
       <xsl:when test="$cliType='directory'"><xsl:value-of select="$directoryValueProperty"/></xsl:when>
       <xsl:when test="$cliType='geometry'"><xsl:value-of select="$geometryValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='integer-vector'"><xsl:value-of select="$integervectorValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='double-vector'"><xsl:value-of select="$doublevectorValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='float-vector'"><xsl:value-of select="$floatvectorValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='string-vector'"><xsl:value-of select="$stringvectorValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='integer-enumeration'"><xsl:value-of select="$integerenumerationValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='double-enumeration'"><xsl:value-of select="$doubleenumerationValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='float-enumeration'"><xsl:value-of select="$floatenumerationValueProperty"/></xsl:when>
-      <xsl:when test="$cliType='string-enumeration'"><xsl:value-of select="$stringenumerationValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='integer-vector'"><xsl:value-of select="$vectorValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='double-vector'"><xsl:value-of select="$vectorValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='float-vector'"><xsl:value-of select="$vectorValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='string-vector'"><xsl:value-of select="$vectorValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='integer-enumeration'"><xsl:value-of select="$enumerationValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='double-enumeration'"><xsl:value-of select="$enumerationValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='float-enumeration'"><xsl:value-of select="$enumerationValueProperty"/></xsl:when>
+      <xsl:when test="$cliType='string-enumeration'"><xsl:value-of select="$enumerationValueProperty"/></xsl:when>
       <xsl:otherwise>value</xsl:otherwise>
     </xsl:choose>
   </xsl:function>

Libs/CommandLineModules/Frontend/QtGui/ctkCmdLineModuleFrontendFactoryQtGui.h

@@ -30,7 +30,12 @@
 /**
  * \class ctkCmdLineModuleFrontendFactoryQtGui
  * \brief Factory class to instantiate Qt widget based front-ends.
- * \ingroup CommandLineModulesFrontendQtGui
+ * \ingroup CommandLineModulesFrontendQtGui_API
+ *
+ * The created front-end instances assume that the CTKWidgetPlugin library (a Qt Designer plug-in)
+ * is available in the applications search path. See also ctkCmdLineModuleFrontendQtGui.
+ *
+ * @see ctkCmdLineModuleFrontendQtGui
  */
 class CTK_CMDLINEMODULEQTGUI_EXPORT ctkCmdLineModuleFrontendFactoryQtGui : public ctkCmdLineModuleFrontendFactory
 {

Libs/CommandLineModules/Frontend/QtGui/ctkCmdLineModuleFrontendQtGui.h

@@ -37,7 +37,64 @@ struct ctkCmdLineModuleFrontendQtGuiPrivate;
 /**
  * \class ctkCmdLineModuleFrontendQtGui
  * \brief A Qt based implementation of the module front end.
- * \ingroup CommandLineModulesFrontendQtGui
+ * \ingroup CommandLineModulesFrontendQtGui_API
+ *
+ * This class is able to generate a Qt widgets based GUI from the XML description of
+ * a given module. It uses a customizable XML stylesheet to transform the raw XML description
+ * into a .ui file which is fed into a QUiLoader to generate the GUI at runtime.
+ *
+ * Sub-classes have several possibilities to customize the generated GUI:
+ * <ul>
+ * <li>Override uiLoader() and provide your own QUiLoader or ctkCmdLineModuleQtUiLoader sub-class
+ *     which knows how to instantiate widget types (see the table below for widget class names).</li>
+ * <li>Bind variables to the ctkCmdLineModuleXslTranform object returned by xslTransform() to
+ *     customize widget class names and property names. This may require you to provide a Qt Designer
+ *     plug-in for your custom widget classes if you do not implement your own widget instantiation
+ *     code in a custom QUiLoader.</li>
+ * <li>Advanced: Override fragments of the XML stylesheet using ctkCmdLineModuleXslTranform::setXslExtraTransformation()</li>
+ * </ul>
+ *
+ * All widget classes are assumed to expose a readable and writable QObject property for storing and
+ * retrieving current front-end values via the DisplayRole role.
+ *
+ * The following table lists the available XSL parameters (setable via ctkCmdLineModuleXslTransform::bindVariable()),
+ * and their default values for all parameter types and created container widgets:
+ *
+ * \htmlonly
+ * <style type="text/css">
+ * table.xslparam { color:#333333; border-collapse:collapse; }
+ * table.xslparam td { border: 1px solid #666666; padding: 5px; }
+ * table.xslparam th { border: 1px solid #666666; padding: 5px; background-color: #dedede; font-weight: bold; }
+ * </style>
+ * <table class="xslparam">
+ * <tr><th rowspan="2">Parameter Type</th><th colspan="4" align="center">XSL Parameters</th></tr>
+ * <tr><th>Widget Class</th><th>Default</th><th>Property Name (DisplayRole)</th><th>Default</th></tr>
+ * <tr><td>boolean</td><td>booleanWidget</td><td>QCheckBox</td><td>booleanValueProperty</td><td>checked</td></tr>
+ * <tr><td>integer</td><td>integerWidget</td><td>QSpinBox</td><td>integerValueProperty</td><td>value</td></tr>
+ * <tr><td>float</td><td>floatingWidget</td><td>QDoubleSpinBox</td><td>floatValueProperty</td><td>value</td></tr>
+ * <tr><td>double</td><td>floatingWidget</td><td>QDoubleSpinBox</td><td>floatValueProperty</td><td>value</td></tr>
+ * <tr><td>integer-vector</td><td>vectorWidget</td><td>QLineEdit</td><td>vectorValueProperty</td><td>text</td></tr>
+ * <tr><td>float-vector</td><td>vectorWidget</td><td>QLineEdit</td><td>vectorValueProperty</td><td>value</td></tr>
+ * <tr><td>double-vector</td><td>vectorWidget</td><td>QLineEdit</td><td>vectorValueProperty</td><td>value</td></tr>
+ * <tr><td>string-vector</td><td>vectorWidget</td><td>QLineEdit</td><td>vectorValueProperty</td><td>value</td></tr>
+ * <tr><td>integer-enumeration</td><td>enumWidget</td><td>QComboBox (ctkCmdLineModuleQtUiLoader instantiates a custom private QComboBox sub-class)</td><td>enumerationValueProperty</td><td>currentEnumeration</td></tr>
+ * <tr><td>float-enumeration</td><td>enumWidget</td><td>QComboBox</td><td>enumerationValueProperty</td><td>currentEnumeration</td></tr>
+ * <tr><td>double-enumeration</td><td>enumWidget</td><td>QComboBox</td><td>enumerationValueProperty</td><td>currentEnumeration</td></tr>
+ * <tr><td>string-enumeration</td><td>enumWidget</td><td>QComboBox</td><td>enumerationValueProperty</td><td>currentEnumeration</td></tr>
+ * <tr><td>file (input channel)</td><td>fileInputWidget</td><td>ctkPathLineEdit</td><td>fileValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>file (output channel)</td><td>fileOutputWidget</td><td>ctkPathLineEdit</td><td>fileValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>geometry (input channel)</td><td>fileInputWidget</td><td>ctkPathLineEdit</td><td>fileValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>geometry (output channel)</td><td>fileOutputWidget</td><td>ctkPathLineEdit</td><td>fileValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>directory</td><td>directoryWidget</td><td>ctkPathLineEdit</td><td>directoryValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>point</td><td>pointWidget</td><td>ctkCoordinatesWidget</td><td>pointValueProperty</td><td>coordinates</td></tr>
+ * <tr><td>region</td><td>pointWidget</td><td>ctkCoordinatesWidget</td><td>pointValueProperty</td><td>coordinates</td></tr>
+ * <tr><td>image (input channel)</td><td>imageInputWidget</td><td>ctkPathLineEdit</td><td>imageValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>image (output channel)</td><td>imageOutputWidget</td><td>ctkPathLineEdit</td><td>imageValueProperty</td><td>currentPath</td></tr>
+ * <tr><td>[main container]</td><td>executableWidget</td><td>QWidget</td><td>n/a</td><td>n/a</td></tr>
+ * <tr><td>[group container]</td><td>parametersWidget</td><td>ctkCollapsibleGroupBox</td><td>n/a</td><td>n/a</td></tr>
+ * <tr><td>[unknown type]</td><td>unsupportedWidget</td><td>QLabel</td><td>n/a</td><td>n/a</td></tr>
+ * </table>
+ * \endhtmlonly
  */
 class CTK_CMDLINEMODULEQTGUI_EXPORT ctkCmdLineModuleFrontendQtGui : public ctkCmdLineModuleFrontend
 {
@@ -49,6 +106,12 @@ public:
 
   // ctkCmdLineModuleFrontend overrides
 
+  /**
+   * @brief Create the actual Qt GUI.
+   * @return The parent widget for the created GUI.
+   *
+   * The returned object is either NULL or can always be casted to QWidget*.
+   */
   virtual QObject* guiHandle() const;
 
   /**
@@ -83,10 +146,52 @@ public:
 
 protected:
 
+  /**
+   * @brief Get the QUiLoader for instantiating widgets.
+   * @return The QUiLoader.
+   *
+   * Override this method to provide your own QUiLoader sub-class for application-specific
+   * customization of certain widgets.
+   *
+   * @see ctkCmdLineModuleQtUiLoader
+   */
   virtual QUiLoader* uiLoader() const;
+
+  /**
+   * @brief Get XSL transform used to transfrom the module XML description to a Qt .ui file.
+   * @return The XSL transform.
+   *
+   * Override this method to either customize the default transformation or completely provide
+   * your own.
+   *
+   * @see ctkCmdLineModuleXslTransform
+   */
   virtual ctkCmdLineModuleXslTransform* xslTransform() const;
 
+  /**
+   * @brief Get the value of the given parameter using the given property name.
+   * @param parameter The parameter name.
+   * @param propertyName The property name from which to get the value.
+   * @return The parameter value for the given property name.
+   *
+   * If \c propertyName is empty, this method returns the value of the property used store the values
+   * for the DisplayRole role.
+   *
+   * Sub-classes can use this method to retrieve values for custom roles.
+   */
   QVariant customValue(const QString& parameter, const QString& propertyName = QString()) const;
+
+  /**
+   * @brief Set the value of the given parameter to \c value using the given property name.
+   * @param parameter The parameter name.
+   * @param value The new value.
+   * @param propertyName The property name for which to set the value.
+   *
+   * If \c propertyName is empty, this method sets the value of the property used store the values
+   * for the DisplayRole role.
+   *
+   * Sub-classes can use this method to set values for custom roles.
+   */
   void setCustomValue(const QString& parameter, const QVariant& value, const QString& propertyName = QString()) ;
 
 private:

Libs/CommandLineModules/Frontend/QtGui/ctkCmdLineModuleQtUiLoader.h

@@ -29,7 +29,7 @@
  * \brief Derived from QUiLoader to enable us to instantiate custom widgets at runtime,
  * where this class provides ctkCmdLineModuleQtComboBox instead of QComboBox.
  * \author m.clarkson@ucl.ac.uk
- * \ingroup CommandLineModulesFrontendQtGui
+ * \ingroup CommandLineModulesFrontendQtGui_API
  */
 class CTK_CMDLINEMODULEQTGUI_EXPORT ctkCmdLineModuleQtUiLoader : public QUiLoader
 {

Libs/CommandLineModules/Frontend/QtWebKit/README.md

@@ -0,0 +1,10 @@
+Qt WebKit Frontend (experimental)    {#CommandLineModulesFrontendQtWebKit_Page}
+=================================
+
+This front-end uses an XML stylesheet to transform the raw XML description of a module
+into a HTML document and uses Qt WebKit to render this document inside a Qt widget.
+
+The front-end is experimental and serves as a *proof-of-concept*, see also the
+ctkCmdLineModuleFrontendQtWebKit class.
+
+See the \ref CommandLineModulesFrontendFactoryQtWebKit_API module for the API documentation.

Libs/CommandLineModules/Frontend/QtWebKit/ctkCmdLineModuleFrontendFactoryQtWebKit.h

@@ -29,7 +29,10 @@
 /**
  * \class ctkCmdLineModuleFrontendFactoryQtWebKit
  * \brief QtWebKit specific implementation of ctkCmdLineModuleFrontendFactory
- * \ingroup CommandLineModulesFrontendQtWebKit
+ * \ingroup CommandLineModulesFrontendQtWebKit_API
+ *
+ * \warning This front-end is highly experimental and actually just serves as a
+ *          proof-of-concept.
  */
 class CTK_CMDLINEMODULEQTWEBKIT_EXPORT ctkCmdLineModuleFrontendFactoryQtWebKit : public ctkCmdLineModuleFrontendFactory
 {

Libs/CommandLineModules/Frontend/QtWebKit/ctkCmdLineModuleFrontendQtWebKit_p.h

@@ -29,7 +29,7 @@ class QWebView;
 /**
  * \class ctkCmdLineModuleFrontendQtWebKit
  * \brief QtWebKit specific implementation of ctkCmdLineModuleFrontend
- * \ingroup CommandLineModulesFrontendQtWebKit
+ * \ingroup CommandLineModulesFrontendQtWebKit_API
  */
 class ctkCmdLineModuleFrontendQtWebKit : public ctkCmdLineModuleFrontend
 {

Libs/CommandLineModules/README.md

@@ -0,0 +1,150 @@
+CTK Command Line Modules   {#CommandLineModules_Page}
+========================
+
+\brief Overview about the Command Line Modules support in CTK.
+
+[TOC]
+
+CTK provides an API for interfacing with self-describing *runnable* modules which can provide an
+XML description of their supported parameters. A runnable module is
+usually (but not constrained to) a local executable and also referred to as a *command line module*.
+
+The XML schema for the parameter description and most of the supported feature set for a module
+has been adopted from the [Slicer Execution Model](http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation).
+
+The API provided by CTK allows the management, GUI generation, and asynchronuous execution
+of such modules in a toolkit-independent and interoperable way. Application writers can rely on the
+provided libraries and their API to quickly integrate command line modules into their applications.
+
+Developers who want to create command line modules which can be run by using the provided tools will
+want to have a look at the *Creating Modules* section below. Everything else targets application writers
+who want to host and mange these command line modules.
+
+CTK also comes with an example application, called *ctkCommandLineModuleExplorer* which can be used
+to load different kinds of modules, to verify their correctness, to run - and finally inspect their output.
+
+
+Features
+--------
+
+Here is short overview about the provided feature set:
+
+- Clear separation in front and back ends (see *Library Design* below)
+- XML validation and error reporting
+- Caching of XML descriptions
+- Partially thread-safe, allowing to concurrently add and remove modules
+- Asynchronuous communication with running modules
+  + Start/pause/cancel support (back-end and operating system dependent)
+  + Result reporting
+  + Output reporting
+
+CTK also provides stable and feature-rich implementations of a Qt based front-end and a back-end handling local processes.
+
+### Qt Gui front-end
+
+The provided front-end implementation creates a Qt widgets based user interface. It also allows to customize the
+GUI generation process, see the ctkCmdLineModuleFrontendQtGui class for more information.
+
+### Local process back-end
+
+The default back-end for running modules can handle local executables and runs them in a separate process. See
+the ctkCmdLineModuleBackendLocalProcess class for details.
+
+
+Creating Modules
+----------------
+
+Module writers usually need to create an XML file describing the parameters which are understood by the module (the actual
+way how such an XML description is provided actually depends on the back-end for which the module is written). For locally
+executable modules (e.g. command line programs), the XML description is usually emitted to the standard output channel by
+the executable itself when it is called with a *--xml* command line argument.
+
+The valid XML structure for the parameter description is defined in the corresponding [schema documentation](ctkCmdLineModule.xsd)
+([absolute link](http://www.commontk.org/docs/html/ctkCmdLineModule.xsd)).
+
+Please note that running a module may fail due to an invalid XML description. The strictness of validation is specific to the
+application you are using to run the module. However, making sure the XML validates agains the given schema (raw schema file
+[here](https://raw.github.com/commontk/CTK/master/Libs/CommandLineModules/Core/Resources/ctkCmdLineModule.xsd)).
+
+### Progress and Result reporting
+
+A module may report progress and intermediate results during its execution. The actual reporting mechanism depends on the type
+of module. For a local executable being run for example by the ctkCmdLineModuleBackendLocalProcess back-end, reporting is done
+by printing XML fragments to the standard output channel.
+
+For example a progress report containing a progress value and text would look like:
+
+    <filter-start>
+      <filter-name>My Filter</filter-name>
+      <filter-comment>Starting custom filter...</filter-comment>
+    </filter-start>
+    <filter-progress-text progress="0.2">Current progress: 0.2 (from [0,1.0])</filter-progress-text>
+    <filter-end/>
+
+Here is the XML [progress and result schema documentation](ctkCmdLineModuleProcess.xsd)
+([absolute link](http://www.commontk.org/docs/html/ctkCmdLineModuleProcess.xsd)) describing the valid XML fragments. The raw
+schema file is available [here](https://raw.github.com/commontk/CTK/master/Libs/CommandLineModules/Core/Resources/ctkCmdLineModuleProcess.xsd).
+
+
+Library Design
+--------------
+
+The Command Line Module support consists of a \subpage CommandLineModulesCore_Page library and so-called
+\subpage CommandLineModulesBackEnds_Page and \subpage CommandLineModulesFrontEnds_Page.
+
+A front-end, a sub-class of ctkCmdLineModuleFrontend, represents a set of parameter values for a specific
+module, usually associated with some kind of user interface. Front-end implementations need not be accessible outside
+of the defining library, but may be exposed to allow the configuration of the GUI generation process by
+sub-classing the corresponding ctkCmdLineModuleFrontendFactory implementation. A front-end can be "run" by
+calling the ctkCmdLineModuleManager::run(ctkCmdLineModuleFrontend*) method and the object returned by the run()
+method is used to communicate with the running module. A front-end can be "run" multiple times (with possibly different
+parameter values) simultaneously.
+
+A back-end, a sub-class of ctkCmdLineModuleBackend, knows how to actually "run" a module. Back-end implementations
+express their capabilities by overriding the ctkCmdLineModuleBackend::schemes() method and providing a list of URL
+schemes this back-end can handle. For example, the ctkCmdLineModuleBackendLocalProcess back-end returns "file" since
+it can handle URLs pointing to local resources (executables). Further, a back-end knows how to get a time-stamp and
+the module XML description for a specific module.
+
+The central class for managing modules is the ctkCmdLineModuleManager. There must be at least one back-end registered
+with the manager for module registrations to succeed. A module is registered by calling the
+ctkCmdLineModuleManager::register(const QUrl&) method, providing the URL to the module. If the URL scheme is not handled
+by a previously registerd back-end, an exception is thrown. If registration succeeds, the method returns a
+ctkCmdLineModuleReference object.
+
+Creating specific front-ends for a given module is actually independent of the ctkModuleManagerManager, except that a
+ctkCmdLineModuleReference object is needed. To create a front-end, usually the
+ctkCmdLineModuleFrontendFactory::create(const ctkCmdLineModuleReference&) method is called, returning a
+ctkCmdLineModuleFrontend pointer.
+
+This separation of concerns in front and back ends allows for an extensible and flexible design. Front-ends and back-ends
+work independent of each other and can be combined arbitrarly.
+
+
+Quick Start
+-----------
+
+Here is a small code example to get you started quickly. We first instantiate a ctkCmdLineModuleManager object, using
+a strict validation mode and the built-in caching mechanism.
+
+\snippet ModuleManager/main.cpp instantiate-mm
+
+Next, we instantiate and register a back-end.
+
+\snippet ModuleManager/main.cpp register-backend
+
+Now we register an executable as a module with the manager.
+
+\snippet ModuleManager/main.cpp register-module
+
+To create a front-end, we use the Qt widgets implementation.
+
+\snippet ModuleManager/main.cpp create-frontend
+
+Last, we run the front-end instance, using the default values for the module parameters.
+
+\snippet ModuleManager/main.cpp run-module
+
+After the ctkCmdLineModuleManager::run() method returns, we wait for the running module to finish and print out
+some data reported by it.
+