oofem-wiki

User Tools

Site Tools

Trace:
coding-conventions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
coding-conventions [2011/01/05 03:00] – More details on doxygen documentation. mikael.ohmancoding-conventions [2011/03/17 13:43] – mikael.ohman
Line 41: Line 41:
 ==== Using comments to document the code ==== ==== Using comments to document the code ====
 OOFEM uses [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] documentation system to automatically generate the reference manual directly from the OOFEM header files. By placing comments in a few strategic places a complete reference manual, including graphics, can be generated. You will typically want to do so for your header files only. OOFEM uses [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] documentation system to automatically generate the reference manual directly from the OOFEM header files. By placing comments in a few strategic places a complete reference manual, including graphics, can be generated. You will typically want to do so for your header files only.
 +
 +If you are overloading methods from another class, you should **leave the documentation empty** and make sure the parameters are named exactly the same. Only write a new documentation field if you have something new to add specifically to the implemented methods.
  
 In general, a special comments should be added straight before each function, variable, class, define, etc. you wish to document. The simplest way is to  add a simple comment with a short documentation string for the entry, e.g.: In general, a special comments should be added straight before each function, variable, class, define, etc. you wish to document. The simplest way is to  add a simple comment with a short documentation string for the entry, e.g.:
Line 102: Line 104:
 </code> </code>
  
-Doxygen will inherit documentation from super classes, so do not add comments unless something specific needs to be said for the implementering routine. Be sure to document all variables and return value, even trivial ones, to avoid reporting errors when generating the documentation. +Again, Doxygen will inherit documentation from super classes, so do not add comments unless something specific needs to be said for the implementing routine. Be sure to document all variables and return value, even trivial ones, to avoid reporting errors when generating the documentation. Currently, OOFEM contains quite a large number of errors in the documentation and a convenient way to list all these errors is to separate the stderr output with the terminal command; 
- +<code> 
-==== Source file layout ==== + doxygen doc/refman/doxygen.cfg 2> dox_errors.txt 
- +</code>
-Each source file, header or implementation file starts with a Subversion identification line and an author line, e.g.: +
- +
-  /* $Id$ */+
  
 === Header file layout === === Header file layout ===
Line 114: Line 113:
 Each header file has the following layout: Each header file has the following layout:
  
-    * Subversion identification line 
     * Copyright notice     * Copyright notice
     * Inclusion protection macro     * Inclusion protection macro
     * Headers file includes     * Headers file includes
     * Forward declarations     * Forward declarations
-    * Actual class definition with DOC++ comments+    * Actual class definition with doxygen comments
  
 For a typical example see element.h. For a typical example see element.h.
Line 125: Line 123:
 Each implementation file has the following layout: Each implementation file has the following layout:
  
-    * Subversion identification line 
     * Copyright notice     * Copyright notice
     * Header file includes     * Header file includes
coding-conventions.txt · Last modified: 2017/11/24 16:45 by bp