summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/coding-style.rst49
1 files changed, 49 insertions, 0 deletions
diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 065fbe0a..8dd1afce 100644
--- a/Documentation/coding-style.rst
+++ b/Documentation/coding-style.rst
@@ -171,6 +171,55 @@ These rules match the `object ownership rules from the Chromium C++ Style Guide`
documented explicitly in details in the API.
+Documentation
+-------------
+
+All public and protected classes, structures, enumerations, macros, functions
+and variables shall be documented with a Doxygen comment block, using the
+Javadoc style with C-style comments. When documenting private member functions
+and variables the same Doxygen style shall be used as for public and protected
+members.
+
+Documentation relates to header files, but shall be stored in the .cpp source
+files in order to group the implementation and documentation. Every documented
+header file shall have a \file documentation block in the .cpp source file.
+
+The following comment block shows an example of correct documentation for a
+member function of the PipelineHandler class.
+
+::
+
+ /**
+ * \fn PipelineHandler::start()
+ * \brief Start capturing from a group of streams
+ * \param[in] camera The camera to start
+ *
+ * Start the group of streams that have been configured for capture by
+ * \a configureStreams(). The intended caller of this method is the Camera
+ * class which will in turn be called from the application to indicate that
+ * it has configured the streams and is ready to capture.
+ *
+ * \return 0 on success or a negative error code otherwise
+ */
+
+The comment block shall be placed right before the function it documents. If
+the function is defined inline in the class definition in the header file, the
+comment block shall be placed alone in the .cpp source file in the same order
+as the function definitions in the header file and shall start with an \fn
+line. Otherwise no \fn line shall be present.
+
+The \brief directive shall be present. If the function takes parameters, \param
+directives shall be present, with the appropriate [in], [out] or [inout]
+specifiers. Only when the direction of the parameters isn't known (for instance
+when defining a template function with variadic arguments) the direction
+specifier shall be omitted. The \return directive shall be present when the
+function returns a value, and shall be omitted otherwise.
+
+The long description is optional. When present it shall be surrounded by empty
+lines and may span multiple paragraphs. No blank lines shall otherwise be added
+between the \fn, \brief, \param and \return directives.
+
+
Tools
-----