-
Notifications
You must be signed in to change notification settings - Fork 485
/
Copy pathindex.html
167 lines (166 loc) · 8.59 KB
/
index.html
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
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>PDR: Doxygen Tutorial</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<link rel="stylesheet" href="../../markdown.css" />
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="pdr-doxygen-tutorial">PDR: Doxygen Tutorial</h1>
<p><a href="../index.html">Go up to the Tutorials table of contents
page</a></p>
<h3 id="what-is-doxygen">What is Doxygen?</h3>
<p><strong>macOS only:</strong> ensure you have <a
href="https://brew.sh/">Homebrew</a> installed and then install Doxygen
and Graphviz using <code>brew install doxygen graphviz</code>.</p>
<p>When writing large amounts of code, it is important to document it,
both for your understanding later, as well as for other people’s
understanding (such as the graders). So far, all of our documentation
has been via regular comments. However, there exist a number of
documentation tools that allow us to do a lot more with our comments.
Consider the Java SDK source code. If you look at the code itself, there
are a lot of comments with special “tags” in the source code. A tag is a
special command that denotes the comment is about some specific aspect,
such as the parameter type or return value. The source code is then run
through a program called javadoc (which comes with the Java SDK), and
the full online HTML documentation pages that we are familiar with are
then created.</p>
<p>Javadoc is great for Java code, but does not work for C++ code. Thus,
we are going to use a program called <a
href="http://www.doxygen.nl">doxygen</a>, which works on a dozen
different languages, including C++. A function might be commented as
follows:</p>
<pre><code>/**
* @brief Computes the average of the two passed values.
*
* This function computes the average using the standard accepted
* formula for doing so.
*
* @return The average of the two passed values.
* @param x The first value to average.
* @param y The second value to average.
* @todo Need to write acceptance tests for this function
*/
double average(double x, double y) {
return (x + y) / 2.0;
}</code></pre>
<p>This is much more documentation than is probably necessary for the
<code>average()</code> function, but the point is to show the
functionality of doxygen. Note that five of the lines have tags, such as
<code>@return</code>, which means that the following comment is
specifically about the return value. Some tags, such as the
<code>@param</code> tag, require a parameter.</p>
<p>Save the above code as a file called <a
href="average.cpp.html">average.cpp</a> (<a href="average.cpp">src</a>).
There is also a <code>main()</code> function in that file that reads in
two doubles, calls <code>average()</code>, and prints out the result;
that function is not commented.</p>
<h3 id="creating-a-doxyfile">Creating a Doxyfile</h3>
<p>We need to tell doxygen what files to process, and a large number of
other options. These are all kept in a file called
<code>Doxyfile</code>. To generate that file, run <code>doxygen
-g</code> in the same directory as the files you want to document (the
<code>-g</code> means “generate”). This will create a Doxyfile with the
default options. We will need to edit it to set a few things. The line
numbers provided are for version 1.8.6 of Doxygen; if you are using a
different version, then your line numbers may vary.</p>
<ul>
<li>The <code>GENERATE_LATEX</code> option (line 1,543): change
<code>YES</code> to <code>NO</code>. We want HTML output (which is
already set to yes), but we don’t want LaTeX output.</li>
<li>The <code>EXTRACT_ALL</code> option (line 401): set to
<code>YES</code>. This will cause Doxygen to create documentation for
<em>all</em> the members in our file, including our
<code>average()</code> function.</li>
<li>The <code>OUTPUT_DIRECTORY</code> option (line 61): set to
<code>doc/</code>. This will cause all the created files to be in the
doc/ sub-directory, and this is <em>necessary</em> for us to find your
files.</li>
<li>The <code>PROJECT_NAME</code> option (line 35): set to <code>"PDR
Lab 11"</code>. This creates the appropriate title for the created
documentation.</li>
<li>You may want to set the <code>QUIET</code> option (line 686) to
<code>YES</code>.</li>
</ul>
<h3 id="running-doxygen">Running Doxygen</h3>
<p>We run doxygen via the <code>doxygen</code> command. The
configuration file you created above produces documentation in just one
form, HTML. With a modification to the configuration file (which we
won’t see here), it can produce documentation in other formats as well
(LaTeX, man pages, XML, RTF, etc).</p>
<p>To see the documentation you generated, go to the
<code>doc/html</code> directory and view
<code>doc/html/index.html</code>. If you look at the documentation for
this function (from the main page, follow the “Files” link on the title
bar, and then the “average.cpp” link), you will see what is below. Note
that there is more to that page than this image; what is below just
shows the extracted documentation for <code>average()</code>.</p>
<p><img src="screenshot.png" /></p>
<p>Do you see how the tags are separated into the different parts of
this comment block?</p>
<h3 id="call-graphs">Call Graphs</h3>
<p>Doxygen can create call graphs for your code. We are going to change
three options to <code>YES</code>: <code>HAVE_DOT</code> (line 2,052),
<code>CALL_GRAPH</code> (line 2,168), and <code>CALLER_GRAPH</code>
(line 2,179). The first one turns on graph creation (“dot” is the
command-line for the graphviz package); the second and third turn on
specific types of graphs.</p>
<p>Now, run <code>doxygen</code> again, and view the page describe above
(the one that shows the contents of average.cpp). You will see a few new
graphs added. Keep in mind that, as the input source code (average.cpp)
was rather small, these graphs are not going to be particularly all that
large, either.</p>
<p>The first graph is a dependency graph:</p>
<p><img src="graph-1.png" /></p>
<p>This shows what the average.cpp file depends on. Specifically, this
is what <code>#include</code> lines it has, which is only iostream in
this case.</p>
<p>The second graph is a callee graph for <code>average()</code>:</p>
<p><img src="graph-2.png" /></p>
<p>This shows that functions and methods call <code>average()</code> –
in this case, it’s only <code>main()</code>.</p>
<p>The third graph is a caller graph for <code>main()</code>:</p>
<p><img src="graph-3.png" /></p>
<p>This shows the functions that <code>main()</code> calls – in this
case, it’s only <code>average()</code>.</p>
<p>As the source code gets larger, so do the graphs. In fact, there is a
maximum limit as to how big the graphs are. Specifically, the
<code>DOT_GRAPH_MAX_NODES</code> option in the Doxyfile (initial value
of 50) limits how many nodes can be represented in a single graph. In
all the three examples shown above, there are only two nodes. After you
start getting toward 100 nodes, the graph starts becoming too large to
see on a screen, and its utility as a visualization tool is lost.</p>
<h3 id="continuing-onward">Continuing Onward</h3>
<p>The <a href="http://www.doxygen.nl/manual/index.html">doxygen
manual</a> has plenty of information on how to use doxygen. You’ll
probably find the <a
href="http://www.doxygen.nl/manual/docblocks.html">Documenting the
code</a> and <a
href="http://www.doxygen.nl/manual/commands.html">Special Commands</a>
chapters to be the most useful.</p>
<h3 id="important-notes">Important Notes</h3>
<p>Private members are not documented in Doxygen by default. To change
this, you will want to change the <code>EXTRACT_PRIVATE</code> flag in
Doxyfile to <code>YES</code>.</p>
<p>You may have to include all of your comments in your .h file. Whether
you have to do this depends on how you structure your code and the code
comments. If you are making changes to your doxygen comments and are not
seeing the results, try moving them to the .h file. As long as the
documentation is created when <code>doxygen</code> is run, we don’t
really care where your doxygen comments are in your source code.</p>
</body>
</html>