The code must be documented with **Doxygen**, an automated tool to generate documentation.
.. rule:: Comment the code
**Doxygen** mainly generates documentation for the code structure. It also is crucial to comment the code where it
is necessary. Please refer to this excellent
`StackOverflow article <https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/>`_. Each
rule in this article has to be followed.
.. 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
...
...
@@ -109,7 +116,7 @@ Example 3 : Function documentation
/**
* ...
* @section Signals Signals
* - \b signal2(::fwData::Mesh::sptr) : Emitted when the mesh has changed.
* - \b signal2(sight::data::Mesh::sptr) : Emitted when the mesh has changed.
* - \b signal1(std::int64_t) : Emitted when ...
*
* @section Slots Slots
...
...
@@ -117,8 +124,9 @@ Example 3 : Function documentation
*/
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.
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
...
...
@@ -137,12 +145,12 @@ Example 3 : Function documentation
``uid`` should have a semantic name. They must be written in lower camel case. Don't prefix the uid by `UID` (like `imageUID`). Moreover, avoid ``uid`` like ``myXXXXX`` or ``customXXXXX``.
``uid`` should have a semantic name. They must be written in lower camel case. Don't prefix the uid by `UID` (like `imageUID`).
Moreover, avoid ``uid`` like ``myXXXXX`` or ``customXXXXX``.
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).
Standard CMake functions and macros should be written in lower case.
.. code-block:: cmake
...
...
@@ -12,12 +12,11 @@ CMakeLists coding
.. rule :: Macro name
Custom macros should be written in camel case.
Custom macros should be written in snake case to follow CMake style.
.. code-block:: cmake
fwLoadProperties()
fwLink("boost")
sight_add_target( module_filter_image TYPE MODULE )
.. rule :: Variable name
...
...
@@ -43,7 +42,8 @@ CMakeLists coding
...
endfunction(name)
This is no longer needed in latest CMake versions, and we recommend to use this possibility for the sake of simplicity.
This is no longer needed in latest CMake versions, and we recommend to use this possibility for the sake of
The file's name should end with the shader's type, ``_VP`` for vertex programs, ``_TC`` for tessellation control programs, ``_FE`` for tessellation evalutaion programs, ``_GP`` for geometry programs and ``_FP`` for fragment programs, ``_VP`` for vertex programs and ``_GP`` for geometry programs.
The file name should end with the shader type, ``_VP`` for vertex programs, ``_TC`` for tessellation control
programs, ``_FE`` for tessellation evaluation programs, ``_GP`` for geometry programs and ``_FP`` for fragment
programs, ``_VP`` for vertex programs and ``_GP`` for geometry programs.
.. rule :: Function and method names
...
...
@@ -70,7 +72,11 @@ Naming conventions
- Length : Len
- Size : Size
#. Vectors representing geometrical and matrices transform. You should specify, if possible, their coordinate system. We define the following notation for the most commonly used spaces: (You may read this `documentation <https://www.khronos.org/opengl/wiki/Vertex_Post-Processing#Perspective_divide>`_ if you don't know them) :
#. Vectors and transformation matrices
You should specify, if possible, their coordinate
system. We define the following notation for the most commonly used spaces (see
For vectors, the coordinate system should be appended to the name. In the case of transform matrices, we need to define both, the destination and source spaces, these should be separated by an underscore with the source being last.
For vectors, the coordinate system should be appended to the name. In the case of transformation matrices, we need
to define both, the destination and source spaces, these should be separated by an underscore with the source
being last.
e.g. m4Ss_Ms defines a matrix transforming model vertices to window space points (often known as the model-view-projection matrix)
e.g. m4Ss_Ms defines a matrix transforming model vertices to window space points (often known as the
model-view-projection matrix)
#. If the variable is normalized, the last character must be ``N``.
- If the answer is no, then you don't need to wrap your data.
- Otherwise, you need to have an object that inherits of ::fwData::Object.
- Otherwise, you need to have an object that inherits of sight::data::Object.
In this latter case, do you need to share this object between different services which use different third-party libraries, i.e. for ::fwData::Image, itk::Image vs vtkImage ?
In this latter case, do you need to share this object between different services which use different third-party libraries,
i.e. for sight::data::Image, itk::Image vs vtkImage ?
- If the answer is yes, then you need create a new object like fwData::Image and a wrapping with fwData::Image<=>itk::Image and fwData::Image<=>vtkImage.
- Otherwise, you can just encapsulated an itk::Image in fwData::Image and create an accessor on it. ( however, this choice implies that all applications that use fwData::Image need ITK library for running. )
- If the answer is yes, then you need create a new object like sight::data::Image and a wrapping with
sight::data::Image<=>itk::Image and sight::data::Image<=>vtkImage.
- Otherwise, you can just encapsulated an itk::Image in sight::data::Image and create an accessor on it. ( however,
this choice implies that all applications that use sight::data::Image need ITK library for running. )
.. _campPath:
...
...
@@ -146,20 +149,20 @@ For instance, the file *fwDataCamp/Image.cpp* shows :
The next lines allows to compile with the support of some external libraries (sight-deps), in this example this is Qt.
The first thing to do is to discover where Qt is installed. This is done with the regular CMake command ``find_package(The_lib COMPONENTS The_component)``.
Then we use ``fwInclude`` to add includes directories to the target, and ``fwLink`` to link the libraries with your target.
Actually if you're accustomed to CMake these two macros are strictly equivalent to:
.. code-block:: cmake
target_include_directories( ${FWPROJECT_NAME} SYSTEM PRIVATE ${Qt5Core_INCLUDE_DIRS} ${Qt5Gui_INCLUDE_DIRS} ${Qt5Widgets_INCLUDE_DIRS} )
They are proposed as a convenience so people won't forget for instance to specify `SYSTEM`,
which prevents compilation warnings from third-part libraries to be displayed.
If the rare case where your module may be a dependency of an another one,
you can forward the include directories and the libraries with ``fwForwardInclude`` and ``fwForwardLink``,
which are still equivalent to ``target_include_directories``
and ``target_link_libraries`` CMake commands but with ``PUBLIC`` set instead of ``PRIVATE``.
Eventually, you can also add custom properties to your target with ``set_target_properties``.
.. _HowTosCMakeProperties.cmake:
Properties.cmake
-----------------
Properties.cmake should contain informations like name, version, dependencies and requirements of the current target.
Here is an example of Properties.cmake from ``fwData`` library:
.. code-block:: cmake
set( NAME fwData )
set( VERSION 0.1 )
set( TYPE LIBRARY )
set( DEPENDENCIES fwCom fwMemory fwTools )
set( REQUIREMENTS )
NAME:
Name of the target
VERSION:
Version of the target
TYPE:
Define the type of the target:
- APP for an "Application"
- MODULE for a "module"
- LIBRARY for a "library"
- EXECUTABLE for an executable
DEPENDENCIES:
Link the target with the given libraries (see `target_link_libraries <http://www.cmake.org/cmake/help/v3.0/command/target_link_libraries.html?highlight=target_link_libraries>`_ ).
The DEPENDENCIES should contain only "library".
REQUIREMENTS:
Ensure that the dependencies are built before the targets (see `add_dependencies <http://www.cmake.org/cmake/help/v3.0/command/add_dependencies.html?highlight=add_dependencies>`_ ).
The REQUIREMENTS should contain only "modules".
Modules without C++ code, like XML-based applications or activities need to ensure that the necessary modules are
built. To achieve that, we use the `add_dependencies()` CMake command.
In some Properties.cmake (mostly in applications), you can see the line:
Last, in XML-based in applications, you will find the line:
