Changes between Initial Version and Version 1 of code/tools/Doxygen

Timestamp:

Sep 21, 2008, 8:39:40 PM (16 years ago)

Author:

landauf

Comment:

—

code/tools/Doxygen

@@ +1 @@
+= Doxygen =
+[[TracNav(TracNav/TOC_Development)]]
+[[TOC]]
+
+[http://www.doxygen.org Doxygen] is a programm that generates a developers manual out of special comments in .cc and .h files.
+
+The main Tags we use are described below:
+
+
+
+== Introductory Comment ==
+Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
+{{{
+/**
+@file
+@brief
+    A brief description.
+
+    More description... (new paragraph after @brief)
+*/
+}}}
+Note: try not to fill in the filename. It is obvious and the comment compiler (Doxygen) will do it automatically and you don't have to adjust it when renaming the file.
+
+== Classes and Structs ==
+In the header file, just above the class declaration, explain what the class does and where it is used. You could even add an example if it helps understanding the class.
+{{{
+/**
+@brief
+    A brief description.
+    More brief description.
+
+    Details follow here.
+    Maybe an example or something.
+*/
+class ClassName
+{
+    ...
+}}}
+
+== Class Members ==
+Add a brief description to every member of a class:
+{{{
+    private:
+        int value_;           //!< A brief description
+        int longerValueName_; //!< A brief description
+}}}
+The < after //! indicates that the member is located in front of the comment instead of after the comment.
+
+If you need a more detailed description, use:
+{{{
+    private:
+        int value_; //!< A detailed description
+                    //!< More detailed description
+                    //!< ...
+}}}
+or
+{{{
+    private:
+        int value_; /**<
+                        A detailed description
+                        More detailed description
+                        ...
+                    */
+}}}
+
+== Functions ==
+Doxygen documentation (javadoc like for C++) is placed in the source file, just above the function header. If the function is inline, place the comment there but keep it short. [[br]]
+When writing documentation in the source file don't make it all jam-packed to enhance readability. Here is an example to demonstrate formatting:
+{{{
+/**
+@brief
+    A brief description.
+    More brief description.
+
+    Details follow here.
+    Maybe an example or something.
+@param param1
+    Parameter description for parameter named 'param1'
+@param param2
+    Parameter description for parameter named 'param2'
+@return
+    Describe what the function returns
+@note
+    Something important to remember.
+@author
+    The mighty whoever
+*/
+returntype functionname(type1 param1, type2 param2)
+{
+    ...
+}}}
+
+== Inline Functions ==
+Inline functions need documentation as well, but we don't want a messy headerfile. Keep the comments short and put all doxygen code on one line:
+{{{
+/** @brief A brief description. @param param1 description [...] @return description */
+inline returntype functionname(type1 param1 [, ...]) { ... }
+}}}
+
+== Full Example ==
+MyClass.h file:
+{{{
+/**
+@file
+@brief
+    A brief description of the file, the classes and macros; links to other files.
+
+    More description... (new paragraph after @brief)
+    Maybe an example or something.
+*/
+
+/**
+@brief
+    A brief description of the class
+
+    Details follow here.
+    More details...
+*/
+class MyClass
+{
+    public:
+        /** @brief A brief description of the inline function. @return description */
+        inline int getValue() const { return this->value_; }
+       
+        void setValue(int value);
+
+    private:
+        int value_; //!< A brief description of the value
+};
+}}}
+
+MyClass.cc:
+{{{
+/**
+@brief
+    A brief description of the function.
+    More brief description.
+
+    Details follow here.
+    Maybe an example or something.
+
+@param value
+    Parameter description for parameter named 'value'
+*/
+void MyClass::setValue(int value)
+{
+    if (value > 0 && value < 10)
+        this->value_ = value;
+}
+}}}
+
+== Also see ==
+  * [http://www.stack.nl/~dimitri/doxygen/docblocks.html this] for more info on doxygen-tags
+  * [http://www.stack.nl/~dimitri/doxygen/commands.html this] for all possible doxygen-tags