Merge branch 'master' of ssh://opencfd@repo.or.cz/srv/git/OpenFOAM-1.5.x
[OpenFOAM-1.5.x.git] / doc / GUIDELINES
blob8038f997de186017c4b2fe1519fc8aa471a0bd0c
1 The guidelines document the current style or a recommended style for
2 documenting OpenFOAM source code (.C and .H) files.
5 General
6 ~~~~~~~
8 - For readability in the comment blocks, certain tags are used that are
9   translated by pre-filtering the file before sending it to doxygen.
11 - The tags start in column 1, the contents follow on the next lines and
12   indented by 4 spaces. The filter removes the leading 4 spaces from the
13   following lines until the next tag that starts in column 1.
15 - The 'Class' and 'Description' tags are the most important ones.
17 - The first paragraph following the 'Description' will be used for the brief
18   description, the remaining paragraphs become the detailed description.
21 eg,
22     |-------------------------
23     |
24     |Class
25     |    Foam::myClass
26     |
27     |Description
28     |    A class for specifying the documentation style.
29     |
30     |    The class is implemented as a set of recommendations that may
31     |    sometimes be useful.
32     |
33     |-------------------------
36 - The class name must be qualified by its namespace, otherwise doxygen
37   will think you are documenting some other class.
39 - If you don't have anything to say about the class (at the moment),
40   use the namespace-qualified class name for the description.
41   This aids with finding these under-documented classes later.
44 eg,
45     |-------------------------
46     |
47     |Class
48     |    Foam::myUnderDocumentedClass
49     |
50     |Description
51     |    Foam::myUnderDocumentedClass
52     |
53     |-------------------------
56 - Use 'Class' and 'Namespace' tags in the header files.
57   The Description block then applies to documenting the class.
59 - Use 'InClass' and 'InNamespace' in the source files.
60   The Description block then applies to documenting the file itself.
62 eg,
63     |-------------------------
64     |
65     |InClass
66     |    Foam::myClass
67     |
68     |Description
69     |    Implements the read and writing of files.
70     |
71     |-------------------------
74 Doxygen Special Commands
75 ~~~~~~~~~~~~~~~~~~~~~~~~
77 Doxygen has a large number of special commands with a '\' prefix or
78 a (alternatively) an '@' prefix.
80 The '@' prefix form is recommended for most doxygen specials, since it has
81 the advantage of standing out. It also happens to be what projects like gcc
82 and VTK are using.
84 The '\' prefix form, however, looks a bit better for the '\n' newline command
85 and when escaping single characters - eg, '\@', '\<', '\>', etc.
88 Since the filtering removes the leading 4 spaces within the blocks,
89 the doxygen commmands can be inserted within the block without problems.
91 eg,
92     |-------------------------
93     |
94     |InClass
95     |    Foam::myClass
96     |
97     |Description
98     |    Implements the read and writing of files.
99     |
100     |    An example input file:
101     |    @verbatim
102     |        patchName
103     |        {
104     |            type        myPatchType;
105     |            refValue    100;
106     |            value       uniform 1;
107     |        }
108     |    @endverbatim
109     |
110     |    Within the implementation, a loop over all patches is done:
111     |    @code
112     |        forAll (patches, patchI)
113     |        {
114     |            ...  // some operation
115     |        }
116     |    @endcode
117     |
118     |-------------------------
121 HTML Special Commands
122 ~~~~~~~~~~~~~~~~~~~~~
124 Since Doxygen also handles HTML tags to a certain extent, the angle brackets
125 need quoting in the documentation blocks. Non-HTML tags cause doxygen to
126 complain, but seem to work anyhow.
129    The template with type <HR> is a bad example.
131    The template with type \<HR\> is a better example.
133    The template with type <Type> causes doxygen to complain about
134    an unknown html type, but it seems to work okay anyhow.
138 Documenting Namespaces
139 ~~~~~~~~~~~~~~~~~~~~~~
141 - If namespaces are explictly declared with the Namespace() macro,
142   they should be documented there.
144 - If the namespaces is used to hold sub-models, the namespace can be
145   documented in the same file as the class with the model selector.
146   eg,
147       documented namespace 'Foam::functionEntries' within the
148       class 'Foam::functionEntry'
150 - If nothing else helps, find some sensible header.
151   eg,
152       namespace 'Foam' is documented in the foamVersion.H file
155 Documenting Typedefs and classes defined via macros
156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
158 ... not yet properly resolved
162 Documenting Applications
163 ~~~~~~~~~~~~~~~~~~~~~~~~
165 Any number of classes might be defined by a particular application, but
166 these classes will not, however, be available to other parts of OpenFOAM. At
167 the moment, the sole purpuse for running doxygen on the applications is to
168 extract program usage information for the '-doc' option.
170 The documentation for a particular application is normally contained within
171 the first comment block in a .C source file. The solution is this to invoke
172 a special filter for the "applications/{solver,utilities}" directories that
173 only allows the initial comment block for the .C files through.
175 The layout of the application documentation has not yet been finalized, but
176 foamToVTK shows an initial attempt.
179 Ignored files and directories
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182 Ignore directories of linked files
183   - */lnInclude/*
185 Ignore test directories
186   - */t/*
188 Ignore applications that clutter everything
190 Ignore application-specific classes
191   - */applications/utilities/*.H
192   - */applications/solvers/*.H
195 Orthography (always good for a flame-war)
196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198 Given the origins of OpenFOAM, the British spellings (eg, neighbour and not
199 neighbor) are generally favoured. For code sections that interact with
200 external libraries, it can be useful to adopt American spellings, especially
201 for names that constitute a significant part of the external library - eg,
202 'color' within graphics sub-systems.
204 Both '-ize' and the '-ise' variant are found in the code comments.
205 If used as a variable or class method name, it is probably better to use '-ize',
206 which is considered the main form by the Oxford University Press.
207     Eg,
208     myClass.initialize()
211 The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
212 seems to confuse non-native (and some native) English speakers.
213 It is better to donate the extra keystrokes and write "it is" or "it has".
214 Any remaining "it's" are likely an incorrect spelling of "its".
218 Housekeeping
219 ~~~~~~~~~~~~
221 The doc/Doxygen/tools directory contains miscellaneous scripts for finding
222 and possibly repairing documentation issues.
225 Updated: 2008-03-17