DocumentationΒΆ
- Rule 41 : Document the code
- The code must be documented with Doxygen, an automated tool to generate documentation.
- Rule 42 : 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 documentation will give more details about algorithms.
Moreover, every documentation must be placed next to the entity it is refering to, in order to help searching inside the code.
- Recommendation 17 : 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. Just use an empty line to make a separation inside a documentation block.
Don’t indicate parameter types when using
@param
directive. This is useless since it will duplicate information of the function prototype. Also, prefer the use of///
whenever possible.
Example 1 : Bad documentation block
/** * @brief A very short description. * * A longer description, giving more details about the documented piece * of code. ********************************************* * @param ********************************************* * @return ********************************************* * @exception ********************************************* * @todo *********************************************
Example 2 : Good documentation block
/** * @brief A very short description. * * A longer description, giving more details about the documented piece * of code. */
Example 3 : Function documentation
class Sample { public: /** * Retrieve the thing. * * @return The thing value. */ const std::string& getThing( void ) const; /** * @brief Set the thing. * * @param thing : The new thing. */ void setThing( const std::string& thing ); private: /// stored thing std::string m_thing; };
- Recommendation 18 : 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 43 : Document service
The service must be properly documented.
This should include first a brief description, then a long description if necessary.
/** * @brief This is the short description. * * This is the long description. *
After that the signals and slots must be documented in two distinct sections.
* * @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. 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.
* * @section XML XML Configuration * * @code{.xml} <service type="::namespace::SService"> <in key="data1" uid="model" /> <inout key="data2" uid="mesh" /> <out key="data3" uid="image2" /> <out key="data4" uid="image1" /> <option1>12</option1> <option2>12</option2> </service> @endcode * @subsection Input Input * - \b data1 [::fwMedData::ModelSeries]: blablabla. * @subsection In-Out In-Out * - \b data2 [::fwData::Mesh]: blablabla. * @subsection Output Output * - \b data3 [::fwData::Image]: blablabla. * - \b data4 [::fwData::Image]: blablabla. * @subsection Configuration Configuration * - \b option1 : first option. * - \b option2(optional) : second option. * */
Please follow the template above as much as possible to keep the documentation as clear and homogeneous as possible.