coding-conventions
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
coding-conventions [2009/06/26 16:36] – added note on running oofem internal tests before commit bp | coding-conventions [2011/03/17 13:43] – mikael.ohman | ||
---|---|---|---|
Line 40: | Line 40: | ||
==== Using comments to document the code ==== | ==== Using comments to document the code ==== | ||
+ | OOFEM uses [[http:// | ||
- | OOFEM uses [[http:// | + | If you are overloading methods from another class, you should **leave the documentation |
- | In general, a special comments should be added straigh | + | In general, a special comments should be added straight |
+ | < | ||
+ | /// Array storing nodal coordinates. | ||
+ | FloatArray coordinates; | ||
- | /// Array storing nodal coordinates. | + | /// Description of enumeration |
- | | + | enum SomeEnum { |
+ | SE_First, | ||
+ | | ||
+ | SE_Third, | ||
+ | } | ||
+ | </ | ||
If you intend to write more than one line of documentation, | If you intend to write more than one line of documentation, | ||
Line 60: | Line 69: | ||
</ | </ | ||
- | DOC++ automatically imposes a hierarchical stucture to the manual entries for classes, structs, unions, enums and interfaces, in that it organizes members of such as sub-entries. If you need to group manual entries, you may do so with the construction: | + | Doxygen |
- | | + | < |
- | | + | /** |
- | | + | * @name <name for the group> |
- | //@{ | + | * < |
+ | */ | ||
+ | ///@{ | ||
<other manual entries> | <other manual entries> | ||
- | | + | ///@} |
+ | </ | ||
This will create an entry with the specified name, that contains all <other manual entries> as sub entries. Note, however, that class members are automatically set as sub entries of the class' | This will create an entry with the specified name, that contains all <other manual entries> as sub entries. Note, however, that class members are automatically set as sub entries of the class' | ||
Line 73: | Line 85: | ||
To document a function or a method of a class, describe the working and usage of the member function, as well as the individual parameters and return values. For example: | To document a function or a method of a class, describe the working and usage of the member function, as well as the individual parameters and return values. For example: | ||
< | < | ||
- | /** | + | /** |
- | * Class implementing node in finite element mesh. Node posses degrees of freedom. | + | * Class implementing node in finite element mesh. Node posses degrees of freedom. |
- | * Node is atribute of few elements and it is managed by domain. | + | * Node is atribute of few elements and it is managed by domain. |
- | * Node manages its positon in space, and optional local coordinate system. | + | * Node manages its positon in space, and optional local coordinate system. |
- | * By default, global coordinate system is assumed in each node. | + | * By default, global coordinate system is assumed in each node. |
- | */ | + | */ |
- | class Node : public DofManager { | + | class Node : public DofManager |
- | + | { | |
- | + | public: | |
- | /** Computes the load vector of receiver in given time. | + | /** |
- | | + | * Computes the load vector of receiver in given time. |
- | | + | * @param answer |
- | | + | * @param stepN Time step when answer is computed. |
+ | * @param mode Determines | ||
*/ | */ | ||
- | virtual void | + | virtual void computeLoadVectorAt(FloatArray & |
- | } | + | } |
</ | </ | ||
- | ==== Source file layout ==== | + | 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 |
- | + | < | |
- | Each source file, header or implementation file starts with a Subversion identification line and an author line, e.g.: | + | doxygen doc/refman/ |
- | + | </code> | |
- | /* $Id$ */ | + | |
=== Header file layout === | === Header file layout === | ||
Line 101: | 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 |
For a typical example see element.h. | For a typical example see element.h. | ||
Line 112: | 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