| 1 |
Generating doxygen output on Windows: |
| 2 |
|
| 3 |
1. Make sure the doc/doxygen/Doxyfile configuration file points to the correct location |
| 4 |
of graphwiz's "dot" exectuable for your system. (DOT_PATH variable) |
| 5 |
2. Load the doxygen configuration file (doc/doxygen/Doxyfile) into the |
| 6 |
doxygen wizard. |
| 7 |
3. Start, output will be put in /doc/doxygen/html. |
| 8 |
|
| 9 |
Generating doxygen output on Linux: |
| 10 |
|
| 11 |
1. Make sure the doc/doxygen/Doxyfile file points to the correct location of |
| 12 |
graphwiz's "dot" exectuable for your system. (DOT_PATH variable) |
| 13 |
2. Run "doxygen doxyfile", output will be put in /doc/doxygen/html |
| 14 |
3. Rumor has it that there is a doxygen wizard (gui) available for linux. |
| 15 |
|
| 16 |
------------------------------------------------------------------------- |
| 17 |
Supplemental Documentation |
| 18 |
|
| 19 |
Supplemental documentation (e.g. Introduction, Summarized class list by |
| 20 |
category etc. are stored in the doc/doxygen/mainpages directory. |
| 21 |
|
| 22 |
How to document classes: |
| 23 |
|
| 24 |
/** |
| 25 |
* @class ClassName |
| 26 |
* |
| 27 |
* @brief Enter a brief description of the |
| 28 |
* class, the first sentence (deliminated by a period) |
| 29 |
* will be included in the brief description. |
| 30 |
* |
| 31 |
* Anything after the first sentence, and included |
| 32 |
* in the "@class" block will be part of the |
| 33 |
* detailed description. |
| 34 |
* |
| 35 |
* The "@brief" description will be used to |
| 36 |
* describe the class on the class list. |
| 37 |
* |
| 38 |
*/ |
| 39 |
|
| 40 |
How to document functions: |
| 41 |
-------------------------- |
| 42 |
|
| 43 |
Keep the Doxygen function documentation with the function definition, e.g. in |
| 44 |
either the .h or the .cpp file. |
| 45 |
|
| 46 |
Placing "/**" before the comments will cause Doxygen to generate a link |
| 47 |
to the function documentation. |
| 48 |
|
| 49 |
/** |
| 50 |
* |
| 51 |
* @brief Description of the function. Will appear before function |
| 52 |
* definition. Don't really need "@brief" as JAVADOC_AUTOBRIEF is |
| 53 |
* turned on. |
| 54 |
* |
| 55 |
* @param Defailed parameter text, if needed. Will appear in |
| 56 |
* separate parameter secion. |
| 57 |
* |
| 58 |
* @retval Detailed text about return value, if needed. |
| 59 |
* |
| 60 |
*/ |
| 61 |
void someFunc() {} |
| 62 |
|
| 63 |
Placing "///" before the comments will cause Doxygen to include the |
| 64 |
associated text next to the function name in the function listing only. |
| 65 |
|
| 66 |
|
| 67 |
Other Notes: |
| 68 |
|
| 69 |
1. Sometimes the html directory has to be cleared out and the entire |
| 70 |
doxygen output regenerated if the graphics get screwed up. |
| 71 |
|
| 72 |
2. Need "dot" from graphwiz. In some doxygen implementations it is |
| 73 |
included. |
| 74 |
|
| 75 |
3. Can generate called/call graphs. To enable or disable call graphs |
| 76 |
for each function, toggle CALL_GRAPH and CALLER_GRAPH variables in the |
| 77 |
config file. To enable for specific functions when CALL_GRAPH is set |
| 78 |
to no, use the @callgraph/@callergraph commands. |
| 79 |
|
| 80 |
4. @sa "See also" alias. |
| 81 |
@note "Note" alias |
| 82 |
@exception |
| 83 |
@class |
| 84 |
@param |
| 85 |
@return |
| 86 |
@retval |
| 87 |
|
| 88 |
ProtoGraph::~Vertice has an example of function text and a @note. |
| 89 |
|
| 90 |
5. Can turn off documentation of inherited functions and properties. |
| 91 |
|
| 92 |
8. We are generating documentation from all src files included under |
| 93 |
the doc tree. This can be changed to include/exclude specific directories. |
| 94 |
|
| 95 |
Modify INPUT in config file to add additional code/directories, e.g. |
| 96 |
|
| 97 |
INPUT = ../common |
| 98 |
|
| 99 |
#Add protolib to the doxygen output |
| 100 |
#INPUT += ../../protolib/common |
| 101 |
|
| 102 |
#To add files |
| 103 |
#INPUT += ../../protolib/common/protoApp.h ../../protolib/common/protoApp.cpp |