Changes between Version 25 and Version 26 of code/C++_styleguide

Timestamp:

Sep 21, 2008, 8:42:55 PM (17 years ago)

Author:

landauf

Comment:

—

code/C++_styleguide

@@ -134 +134 @@
 
 == Comments ==
-
-=== 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 ===
-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 [, ...]) { ... }
-}}}
+Comment your code and add [wiki:Doxygen] Comments to all files, classes, structs, functions and member variables.[[br]]
+Read [wiki:Doxygen this] to learn more about Doxygen.
 
 ----