doc/GUIDELINES

   1 The guidelines document the current style or a recommended style for
   2 documenting OpenFOAM source code (.C and .H) files.
   3
   4
   5 General
   6 ~~~~~~~
   7
   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.
  10
  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.
  14
  15 - The 'Class' and 'Description' tags are the most important ones.
  16
  17 - The first paragraph following the 'Description' will be used for the brief
  18   description, the remaining paragraphs become the detailed description.
  19
  20
  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     |-------------------------
  34
  35
  36 - The class name must be qualified by its namespace, otherwise doxygen
  37   will think you are documenting some other class.
  38
  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.
  42
  43
  44 eg,
  45     |-------------------------
  46     |
  47     |Class
  48     |    Foam::myUnderDocumentedClass
  49     |
  50     |Description
  51     |    Foam::myUnderDocumentedClass
  52     |
  53     |-------------------------
  54
  55
  56 - Use 'Class' and 'Namespace' tags in the header files.
  57   The Description block then applies to documenting the class.
  58
  59 - Use 'InClass' and 'InNamespace' in the source files.
  60   The Description block then applies to documenting the file itself.
  61
  62 eg,
  63     |-------------------------
  64     |
  65     |InClass
  66     |    Foam::myClass
  67     |
  68     |Description
  69     |    Implements the read and writing of files.
  70     |
  71     |-------------------------
  72
  73
  74 Doxygen Special Commands
  75 ~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 Doxygen has a large number of special commands with a '\' prefix or
  78 a (alternatively) an '@' prefix.
  79
  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.
  83
  84 The '\' prefix form, however, looks a bit better for the '\n' newline command
  85 and when escaping single characters - eg, '\@', '\<', '\>', etc.
  86
  87
  88 Since the filtering removes the leading 4 spaces within the blocks,
  89 the doxygen commmands can be inserted within the block without problems.
  90
  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     |-------------------------
 119
 120
 121 HTML Special Commands
 122 ~~~~~~~~~~~~~~~~~~~~~
 123
 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.
 127
 128 eg,
 129    The template with type <HR> is a bad example.
 130
 131    The template with type \<HR\> is a better example.
 132
 133    The template with type <Type> causes doxygen to complain about
 134    an unknown html type, but it seems to work okay anyhow.
 135
 136
 137
 138 Documenting Namespaces
 139 ~~~~~~~~~~~~~~~~~~~~~~
 140
 141 - If namespaces are explictly declared with the Namespace() macro,
 142   they should be documented there.
 143
 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'
 149
 150 - If nothing else helps, find some sensible header.
 151   eg,
 152       namespace 'Foam' is documented in the foamVersion.H file
 153
 154
 155 Documenting Typedefs and classes defined via macros
 156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 157
 158 ... not yet properly resolved
 159
 160
 161
 162 Documenting Applications
 163 ~~~~~~~~~~~~~~~~~~~~~~~~
 164
 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.
 169
 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.
 174
 175 The layout of the application documentation has not yet been finalized, but
 176 foamToVTK shows an initial attempt.
 177
 178
 179 Ignored files and directories
 180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 181
 182 Ignore directories of linked files
 183   - */lnInclude/*
 184
 185 Ignore test directories
 186   - */t/*
 187
 188 Ignore applications that clutter everything
 189
 190 Ignore application-specific classes
 191   - */applications/utilities/*.H
 192   - */applications/solvers/*.H
 193
 194
 195 Orthography (always good for a flame-war)
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 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.
 203
 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()
 209
 210
 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".
 215
 216
 217
 218 Housekeeping
 219 ~~~~~~~~~~~~
 220
 221 The doc/Doxygen/tools directory contains miscellaneous scripts for finding
 222 and possibly repairing documentation issues.
 223
 224
 225 Updated: 2008-03-17