diff --git a/doc/contributing/source/coding-style.rst b/doc/contributing/source/coding-style.rst index e6dd0a9bb..5e89bbf05 100644 --- a/doc/contributing/source/coding-style.rst +++ b/doc/contributing/source/coding-style.rst @@ -798,6 +798,70 @@ that usage is consistent within a file. MyClass(int n); }; +All the functions and variables must be documented, with the exception of +member functions inherited from parent classes (the documentaion is copied +automatically from the parent class), and default constructor/destructor. + +It is strongly suggested to use grouping to bind together logically related +classes (e.g., all the classes in a module). E.g.; + +.. sourcecode:: cpp + + /** + * \defgroup mynewmodule This is a new module + */ + + /** + * \ingroup mynewmodule + * + * MyClassOne description. + */ + class MyClassOne + { + }; + + /** + * \ingroup mynewmodule + * + * MyClassTwo description. + */ + class MyClassTwo + { + }; + +In the tests for the module, it is suggested to add an ancillary group: + +.. sourcecode:: cpp + + /** + * \defgroup mynewmodule-test Tests for new module + * \ingroup mynewmodule + * \ingroup tests + */ + + /** + * \ingroup mynewmodule-tests + * \brief MyNewModule Test + */ + class MyNewModuleTest : public TestCase + { + }; + + /** + * \ingroup mynewmodule-tests + * \brief MyNewModule TestSuite + */ + class MyNewModuleTestSuite : public TestSuite + { + public: + MyNewModuleTestSuite(); + }; + + /** + * \ingroup mynewmodule-tests + * Static variable for test initialization + */ + static MyNewModuleTestSuite g_myNewModuleTestSuite; As for comments within the code, comments should be used to describe intention or algorithmic overview where is it not immediately obvious from reading the