merge(improve-user-documentation): into dev

fw4spl-org · May 24, 2018 · f90ba33 · f90ba33
2 parents 0488718 + 2eac24c
commit f90ba33
Show file tree

Hide file tree

Showing 37 changed files with 1,771 additions and 811 deletions.
diff --git a/CMake/index.rst b/CMake/index.rst
diff --git a/CMake/src/Cmake_Tutorials.rst b/CMake/src/Cmake_Tutorials.rst
diff --git a/CMake/src/introduction.rst b/CMake/src/introduction.rst
diff --git a/CodingStyle/src/cmake-style.rst b/CodingStyle/src/cmake-style.rst
@@ -5,7 +5,7 @@ CMakeLists coding
 
     Standard CMake functions and macros should be written in lower case. Each word is generally separated by an underscore (this is a rule of CMake anyway).
 
-    .. code-block :: cmake
+    .. code-block:: cmake
 
         add_subdirectory("library/")
         include_directories(SYSTEM "/usr/local")
@@ -14,7 +14,7 @@ CMakeLists coding
 
     Custom macros should be written in camel case.
 
-    .. code-block :: cmake
+    .. code-block:: cmake
 
         fwLoadProperties()
         fwLink("boost")
@@ -23,15 +23,15 @@ CMakeLists coding
 
     Variables should be written in upper case letters separated if needed by underscores.
 
-    .. code-block :: cmake
+    .. code-block:: cmake
 
         set(VARIABLE_NAME "")
 
 .. recommendation :: Expression in block ending
 
     In the past, CMake enforced to specify the label or expression in block ending, for instance :
 
-    .. code-block :: cmake
+    .. code::
 
         function(name arg1 arg2)
             ...
@@ -45,7 +45,7 @@ CMakeLists coding
 
     This is no longer needed in latest CMake versions, and we recommend to use this possibility for the sake of simplicity.
 
-    .. code-block :: cmake
+    .. code:: 
 
         function(name arg1 arg2)
             ...
@@ -56,4 +56,3 @@ CMakeLists coding
             endif()
             ...
         endfunction()
-
diff --git a/CodingStyle/src/documentation.rst b/CodingStyle/src/documentation.rst
@@ -1,11 +1,13 @@
+.. _Documentation:
+
 Documentation
 =============
 
-.. rule :: Document the code
+.. rule:: Document the code
 
     The code must be documented with **Doxygen**, an automated tool to generate documentation.
 
-.. rule :: Location of the documentation
+.. rule:: Location of the documentation
 
     Every documentation that can be useful to a user must be placed inside the header files. Thus a user of a module can
     find the declaration of a class and its documentation at the same place. Inside the implementation file, the
@@ -14,7 +16,7 @@ Documentation
     Moreover, every documentation must be placed next to the entity it is refering to, in order to help searching inside
     the code.
 
-.. recommendation :: Lightweight documentation
+.. recommendation:: Lightweight documentation
 
     Inside a documentation block, only use necessary tags. This will avoid to overload the documentation and makes it
     readable. By the way, empty tags will be presented inside the generated documentation and will be useless.
@@ -79,46 +81,48 @@ Example 3 : Function documentation
             std::string     m_thing;
         };
 
-.. recommendation :: Structured documentation
+.. recommendation:: Structured documentation
 
     Doxygen provides a default structure when you generate the documentation. However, when dealing with a big
     documented entity, it is often recommended to use the group feature (``@name``). With this feature you will build a
     logical view of the class interfaces.
 
-.. rule :: Document service
+.. rule:: Document service
 
-    The service must be properly documented. 
+    The service must be properly documented.
 
     This should include first a brief description, then a long description if necessary.
 
     .. code-block:: cpp
 
         /**
          * @brief This is the short description.
-         * 
+         *
          * This is the long description.
          *
 
     After that the signals and slots must be documented in two distinct sections.
 
     .. code-block:: cpp
 
-         *
+        /**
+         * ...
          * @section Signals Signals
          * - \b signal2(::fwData::Mesh::sptr) : Emitted when the mesh has changed.
          * - \b signal1(std::int64_t) : Emitted when ...
          *
          * @section Slots Slots
          * - \b modified() : Modify the data.
-         *
+         */
 
-    Last the xml configuration of the service must be described into a dedicated section. 
+    Last the xml configuration of the service must be described into a dedicated section.
     It should indicate first the input, input/outputs and outputs in three subsections. The type and the name of the data should appear along with a short description.
     A fourth subsection  describes the rest of the parameters, and tells if it they are optional or not.
 
     .. code-block:: cpp
 
-         *
+        /**
+         * ...
          * @section XML XML Configuration
          *
          * @code{.xml}
@@ -144,5 +148,11 @@ Example 3 : Function documentation
          *
          */
 
-    Please follow the template above as much as possible to keep the documentation as clear and homogeneous as possible.
+    **The XML documentation is important**, it is parsed to register properly the service.
+    The `Input`, `Output` and `InOut` sections must follow the defined format:
+
+        \\- \\b ``key_name`` [``object_type``]: ``description``
 
+    - *key_name*: the name of the key (used to retrieve the object in the service)
+    - *object_type*: class of the object with the full namespace (don't forget the ``::``)
+    - *description*: the purpose of this input/output