Doxygen code comment rules

Package definition

Source code

The file "__ init __.py" starts with the following package definition for Doxygen:

""" @package <Package name>
<Package short description>

<Package full description>
"""

Where:

• <Package name> has to be replaced by the name of the package
• <Package short description> has to be replaced by a short description of the package (no line break, two sentences maximum).
• <Package full description> has te be replaced by the full description of the package (line breaks, multiple sentences)

Test code

Same rule applies for the file "conftest.py"

Module definition

Source code

The main file of the module starts with the module definition for Doxygen:

"""@defgroup <Module name>
<Module short description>
"""

Where:

• <Module name> has to be replaced by the name of the module
• <Module short description> has to be replaced by a short description of the module (no line break, two sentences maximum).

Test code

Same rule applies for each test file

Class definition

The following rules apply for source and test codes

The declaration of a class is followed by the following class definition for Doxygen:

"""@ingroup <Module name>
@anchor <Class name>
<Class short description>

<Class full description>
"""

Where:

• <Module name> has to be replaced by the name of the module
• <Class name> has to be replaced by the name of the class
• <Class short description> has to be replaced by a short description of the class (no line break, two sentences maximum).
• <Class full description> has to be replaced by the full description of the class (line breaks, multiple sentences)

Thanks to this definition the class can be referenced in other code comments by using the Doxygen special command @ref <Class name>

Class attribute definition

The following rules apply for source and test codes

The declaration of the constructor "__ init __" of a class is followed by the following definition of its attributes for Doxygen:

""" @var <Attribute name 1>
<Attribute short description>\n
<Attribute full description>

(...)

@var <Attribute name n>
<Attribute short description>\n
<Attribute full description>
"""

Where:

• <Attribute name> has to be replaced by the name of the attribute
• <Attribute short description> has to be replaced by a short description of the attribute (no line break, two sentences maximum).
• <Attribute full description> has to be replaced by the full description of the attribute (line breaks, multiple sentences). Line breaks must be done using the carriage return \n

Method definition

Source code

The declaration of a method is followed by the following method definition for Doxygen:

"""@ingroup <Module name>
<Method description>
@param[in] <Input name> : <Input description>
@param[out] <Output name> : <Output description>
@return <Return description>
"""

Where:

• <Module name> has to be replaced by the name of the module
• <Method description> has to be replaced by a short description of the method (no line break, two sentences maximum).
• The doxygen special command @param[in] is used to define an input if any:
  • <Input name> has to be replaced by the input name
  • <Input description> has to be replaced by a short description of the input (no line break, two sentences maximum).
• The doxygen special command @param[out] is used to define an output if any:
  • <Output name> has to be replaced by the output name
  • <Output description> has to be replaced by a short description of the output (no line break, two sentences maximum).
• The doxygen special command @return is used to define the returned value:
  • <Return description> has to be replaced by a short description of the returned value (no line break, two sentences maximum).
  • If no value is returned, then <Return description> has to be replaced by "None"

Test code

Same rule applies for each test method.

Additional rule: the test method name begins with test_

Additional rule: the test method name refers explicity to the name of a test module as followed:

• Methods refering to the module "test_plantuml_context" has a name ending with _plantuml_context
• Methods refering to the module "test_plantuml_decomposition" has a name ending with _plantuml_decomposition
• Methods refering to the module "test_plantuml_sequence" has a name ending with _plantuml_definition
• Methods refering to the module "test_plantuml_state" has a name ending with _plantuml_state
• Methods refering to the module "test_input_cell" has a name ending with _in
• Methods refering to the module "test_magic_tools" has a name ending with _tool
• Methods refering to the module "test_question_answer" has a name ending with _answer
• Methods refering to the module "test_xml_file" has a name ending with _xml

Input vector definition

The following rules apply for test code only

The declaration of an input vector in the file "conftest.py" is followed by the following definition for Doxygen:

""" @ingroup <test module>
@anchor <input vector name>
Defines input fixture for @ref <test name>

@return input fixture

**Jarvis4se equivalent:**

<Jarvis commands list>
"""

Where:

• <test module> has to be replaced by the module name for which the input vector is applicable
  • If the input vector is used by different tests defined in different test modules, then the most relevant test module name has to be taken.
• <input vector name> has to be replaced by the input vector name
  • The input vector name begins with "input_"
• <test name> has to be replaced by the test name for which the input vector is applicable
  • If the input vector is used by different tests, then the doxygen special command @ref has to be used before each test name
• <Jarvis commands list> has to be replaced by the list of Jarvis commands defining the input vector
  • The list contains only one Jarvis command per line