Changes between Version 20 and Version 21 of CodingStyle

Timestamp:

Oct 5, 2008, 7:14:28 AM (16 years ago)

Author:

Christian Beer

Comment:

first try to set a documentation policy for inline commentsto convert to doxygen. Please comment.

CodingStyle

@@ -14 +14 @@
 === Code documentation ===
 
- * `.C` files have a comment at the top saying what's in the file (and perhaps what isn't).
+ * `.cpp` files have a comment at the top saying what's in the file (and perhaps what isn't).
  * Functions are preceded by a comment saying what they do.
  * structs and classes are preceded by a comment saying what they are.
@@ -76 +76 @@
 === Comments and #ifdefs ===
 
- * Use `//` for all comments.
+ * Use `///` for all comments. The documentation is generated using Doxygen, so you should have a look at this example:
+
+{{{
+/// Brief description for class test.
+
+/// A more elaborate description for class test,
+/// could be more than one line.
+class Test
+{
+  public:
+
+    /// A constructor.
+      
+    /// A more elaborate description of the constructor.
+    Test();
+
+    /// A destructor.
+    /// A more elaborate description of the destructor.
+    ~Test();
+    
+    /// a normal member taking two arguments and returning an integer value.
+    /// @param a an integer argument.
+    /// @param s a constant character pointer.
+    /// @see Test()
+    /// @see ~Test()
+    /// @see testMeToo()
+    /// @see publicVar()
+    /// @return The test results
+    int testMe(int a,const char *s);
+       
+    /// A pure virtual member.
+    /// @see testMe()
+    /// @param c1 the first argument.
+    /// @param c2 the second argument.
+    virtual void testMeToo(char c1,char c2) = 0;
+   
+    /// a public variable.
+
+    /// Details.
+    int publicVar;
+       
+    /// a function variable.
+
+    /// Details.
+    int (*handler)(int a,int b);
+};
+
+}}}
+
  * Comment out blocks of code as follows:
 {{{
@@ -88 +136 @@
 === Includes ===
 
- * A `.C` file should have the minimum set of #includes to get that particular file to compile (e.g. the includes needed by {{{foo.C}}} should be in {{{foo.C}}}, not {{{foo.h}}}).
+ * A `.cpp` file should have the minimum set of #includes to get that particular file to compile (e.g. the includes needed by {{{foo.cpp}}} should be in {{{foo.cpp}}}, not {{{foo.h}}}).
  * Includes should be ordered from general (`<stdio.h>`) to specific (`thisfile.h`).
 
 === Extern declarations ===
 
- * {{{foo.h}}} should have '{{{extern}}}' declarations for all public functions and variables in {{{foo.C}}} There should be no '{{{extern}}}' statements in {{{.C}}} files.
+ * {{{foo.h}}} should have '{{{extern}}}' declarations for all public functions and variables in {{{foo.cpp}}} There should be no '{{{extern}}}' statements in {{{.cpp}}} files.
 
 === Use of static ===