| 1 | | to change options in setup file (Doxyfile) do |
| | 1 | Readme for Doxygen |
| | 2 | |
| | 3 | quick start: |
| | 4 | create the documentation with the command |
| | 5 | doxygen Doxyfile |
| | 6 | |
| | 7 | Doxygen is a source code documentation system that is widely used in open source projects. It is available on the web at http://www.stack.nl/~dimitri/doxygen/ You will need a copy of the doxygen executable on your system to create the documentation. |
| | 8 | |
| | 9 | Doxygen must be able to find the open source program graphviz that is used to create equations from embedded LaTex. Download graphviz from http://www.graphviz.org/ |
| | 10 | |
| | 11 | This directory includes the setup file "Doxyfile" that is needed to run doxygen. The Cloudy download does not include the output documentation it generates. To create documentation run doxygen with the command |
| | 12 | doxygen Doxyfile |
| | 13 | in this directory. Doxgyen will create a new html directory below this one. The index.html file in the html directory is the top of the documentation. |
| | 14 | |
| | 15 | The manual for doxygen can be found at http://www.stack.nl/~dimitri/doxygen/download.html#latestman |
| | 16 | The full description of its commands is under "Special Commands" in the "Reference Manual" section. |
| | 17 | |
| | 18 | The document file doxygen_setup_style.txt in this directory contains some notes on how Cloudy uses doxygen. |
| | 19 | |
| | 20 | ============================================== |
| | 21 | |
| | 22 | the file Doxyfile was created with the gui that is lauchned with the command |
| 5 | | expert tab has many options |
| 6 | | |
| 7 | | to run doxygen and create output do |
| 8 | | doxygen Doxyfile |
| 9 | | in this directory |
| 10 | | |
| 11 | | check whether INPUT parameter in Doxyfile is set to source_hot or source - this changes |
| 12 | | source is the archived version and source_hot is the local development version |
| 13 | | |
| 14 | | to generate the ouput doxygen also needs graphviz, another open source app. graphviz needs |
| 15 | | to be on the path for doxygen to find it. |
| 16 | | |
| 17 | | Doxyfile is set up to create only html output. other options are possible. The html will be |
| 18 | | in the html directory below this main directory. |
| 19 | | |
| 20 | | Within the codebase, doxygen markup is fully contained in the headers. All doxygen special comment blocks are using the "C style" markup. Special comment blocks are indicated by /**. Commands are indicated with the with the syntax \command. All comment blocks are immediately before what they describe, with the exception of some struct members, where the comment immediately follows ("/**<" syntax). Within special commente blocks, the \, @, &, $, #, <, >, % characters must be escaped using a preceeding \ |
| 21 | | |
| 22 | | The following commands are in use: |
| 23 | | \file <filename> (description) - description for a file, will appear in the output above any descriptions of items contained in the file. |
| 24 | | \verbatim - Doxygen outputs text enclosed in verbatim/endverbatim tags exactly (ie, preserving whitespace and newlines) |
| 25 | | \endverbatim |
| 26 | | \param [in|out|in,out] <parameter name> (description) - describe a parameter of a function. Parameter name is the name of the variable and does not include type. [in|out|in,out] is optional. |
| 27 | | \post (description) - describe the post conditions for a function |
| 28 | | \return (description) - describe what the function returns (in output "Returns "+description is printed) |
| 29 | | \author Joe Blow |
| 30 | | |
| 31 | | latex in line |
| 32 | | \f$ - same as in line $ - opposite is another \f$ |
| 33 | | |
| 34 | | The ideal declaration should look like the following: |
| 35 | | ======================================================= |
| 36 | | |
| 37 | | /** |
| 38 | | routine_name This is the long description of what routine_name does, appears after |
| 39 | | the function name |
| 40 | | \brief this is routine brief description - only 1 line long |
| 41 | | \param iz a description of what parameter 1 is for |
| 42 | | \param [in] in a description of what parameter 2 is for |
| 43 | | \param [out] *out description |
| 44 | | \author Joe Blow |
| 45 | | \return explain the return value |
| 46 | | */ |
| 47 | | double routine_name(long int iz, |
| 48 | | long int in , |
| 49 | | double *out ); |
| 50 | | |
| 51 | | ======================================================= |
| 52 | | |
| 53 | | The manual for doxygen can be found: http://www.stack.nl/~dimitri/doxygen/download.html#latestman |
| 54 | | The full description of these commands and all others are under "Special Commands" in the "Reference Manual" section. |
| | 26 | Good luck, |
| | 27 | Gary Ferland |
| | 28 | http://www.nublado.org |
