Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# Doxygen instructions
**A quick run down of using doxygen**
## Intro
Basically Doxygen is going to look at every `.cpp` and `.h` file and look out for specifically formatted comments.
The full documentation can be [found here](http://www.doxygen.nl/manual/docblocks.html), but here is enough to get started. A Doxyfile has already been generated and options can be tweaked as necessary.
### install
#### Windows
You can install the binary [following these instruction](http://www.doxygen.nl/manual/install.html#install_bin_windows)
#### macOS
```
brew install doxygen
```
#### Linux Ubuntu / Debian
```
sudo apt-get install doxygen
```
### Comment blocks
Comment blocks can take a number of forms but I suggest using Javadoc c-style comments
> ... starting with two \*'s, like this:
>
> ```cpp
> /**
> * ... text ...
> */
> ```
#### Commands
Commands basically allow for comments to broken down into sections. They can start with either `\` or `@`.
There are a ton of different commands, though all the is needed is just a `\brief` tag at most. [A full reference can be found here](http://www.doxygen.nl/manual/commands.html). You don't need to be beholden to these commands, [you can use your own custom commands if you like](http://www.doxygen.nl/manual/custcmd.html).
A boiler plate commented file would look something like
```cpp
/** \file filename.h
\brief A Documented file.
filename.h MUST be the same name as the actual file
*/
/** \class Test
\brief A test class.
A more detailed class description.
*/
class Test{};
/**
\fn void example(int arg1);
\brief an example function
\param arg1 the first argument
*/
void example(int arg1);
```
The `doxygen_test.h` is provided as an example.
### Running Doxygen
run in the command line as
```sh
cd path/to/repo/
doxygen Doxyfile
```
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
### Markdown
[Doxygen supports Markdown!](http://www.doxygen.nl/manual/markdown.html) So you can use markdown in comment blocks if necessary.
In the doxygen file you can also point the frontpage to a `.md` file.
```make
USE_MDFILE_AS_MAINPAGE =
```
This will populate the mainpage with html from the specified markdown file.
### Custom Output
You can specify a html header, footer and custom css files. The easiest approach would be to generate these first
```sh
doxygen -w html header.html footer.html customdoxygen.css
```
then edit them as necessary.
Change these options in the Doxyfile
```make
HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_EXTRA_STYLESHEET = my_customdoxygen.css
```