Changes between Version 20 and Version 21 of CodingStyle

Show
Ignore:
Author:
ChristianB (IP: 89.57.25.218)
Timestamp:
10/05/08 07:14:28 (1 year ago)
Comment:

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

Legend:

Unmodified
Added
Removed
Modified

  • CodingStyle

    v20 v21  
    1414=== Code documentation === 
    1515 
    16  * `.C` files have a comment at the top saying what's in the file (and perhaps what isn't). 
     16 * `.cpp` files have a comment at the top saying what's in the file (and perhaps what isn't). 
    1717 * Functions are preceded by a comment saying what they do. 
    1818 * structs and classes are preceded by a comment saying what they are. 
    7676=== Comments and #ifdefs === 
    7777 
    78  * Use `//` for all comments. 
     78 * Use `///` for all comments. The documentation is generated using Doxygen, so you should have a look at this example: 
     79 
     80{{{ 
     81/// Brief description for class test. 
     82 
     83/// A more elaborate description for class test, 
     84/// could be more than one line. 
     85class Test 
     86{ 
     87  public: 
     88 
     89    /// A constructor. 
     90       
     91    /// A more elaborate description of the constructor. 
     92    Test(); 
     93 
     94    /// A destructor. 
     95    /// A more elaborate description of the destructor. 
     96    ~Test(); 
     97     
     98    /// a normal member taking two arguments and returning an integer value. 
     99    /// @param a an integer argument. 
     100    /// @param s a constant character pointer. 
     101    /// @see Test() 
     102    /// @see ~Test() 
     103    /// @see testMeToo() 
     104    /// @see publicVar() 
     105    /// @return The test results 
     106    int testMe(int a,const char *s); 
     107        
     108    /// A pure virtual member. 
     109    /// @see testMe() 
     110    /// @param c1 the first argument. 
     111    /// @param c2 the second argument. 
     112    virtual void testMeToo(char c1,char c2) = 0; 
     113    
     114    /// a public variable. 
     115 
     116    /// Details. 
     117    int publicVar; 
     118        
     119    /// a function variable. 
     120 
     121    /// Details. 
     122    int (*handler)(int a,int b); 
     123}; 
     124 
     125}}} 
     126 
    79127 * Comment out blocks of code as follows: 
    80128{{{ 
    88136=== Includes === 
    89137 
    90  * 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}}}). 
     138 * 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}}}). 
    91139 * Includes should be ordered from general (`<stdio.h>`) to specific (`thisfile.h`). 
    92140 
    93141=== Extern declarations === 
    94142 
    95  * {{{foo.h}}} should have '{{{extern}}}' declarations for all public functions and variables in {{{foo.C}}} There should be no '{{{extern}}}' statements in {{{.C}}} files. 
     143 * {{{foo.h}}} should have '{{{extern}}}' declarations for all public functions and variables in {{{foo.cpp}}} There should be no '{{{extern}}}' statements in {{{.cpp}}} files. 
    96144 
    97145=== Use of static === 
If this page is incomplete or incorrect, please edit it or add it to the wiki to-do list. To do this, you must be logged in; click Login or Register above.