Kirk Rader  1.0-SNAPSHOT
Using Doxygen

Table of Contents

Documenting Java code using Doxygen.

Overview

This documentation was generated from Java sources using Doxygen. See http://www.stack.nl/~dimitri/doxygen/index.html.

Doxygen generates richly formatted output in a variety of formats from javadoc-style comment blocks in a number of programming languages. For example, simply by adding a Doxyfile configuration file to your source files, you can generate both HTML and PDF output from Java code with no other changes – unlike the native javadoc processor which only supports HTML output.

Basic Formatting

Doxygen goes beyond the native javadoc process in supporting richer content using a simpler syntax. For example, you can use Markdown syntax rather than embedded HTML for things like font styles, hyperlinks etc. For example:

- _italics_
- **bold face**
- `monospaced text`
- [Markdown](https://daringfireball.net/projects/markdown/)

renders as:

Overall, this results in far more legible code when reading the javadoc comment blocks directly in the source files than embedding the equivalent HTML tags.

PlantUML

With additional external configuration, you can embed PlantUML diagrams directly in your javadoc comment blocks. For example:

@startuml
participant client as A
participant service as B
participant backend as C
A -> B: request
activate B
B -> B: validate
opt valid
 B -> C: process
 C -> B: result
end
B -> A: response
deactivate B
@enduml

renders as:

This requires that the location of the PlantUML JAR file be specified in your Doxyfile. This project's configuration files can be used as a template. In particular, this project's pom.xml and Doxyfile are designed to work together such that mvn install will pass the artifact id, version number and other build-time variables to Doxygen which will then place the generated documentation in a subdirectory of the standard Maven target directory. Also, this project's Doxyfile assumes that a "system" environment variable named PLANTUML_JAR contains the absolute path of the PlantUML JAR file.

Attention
Using an environment variable rather than a hard-coded path in Doxyfile makes the build portable between development environments and build platforms but requires external configuration of the build environment. This can be mitigated using techniques like Maven profiles but at the cost that you can then only invoke doxygen through the use of build scripts rather than directly at the command line.

LaTeX

You can embed LaTeX formulas both inline or as block equations. For example:

Here is a sentence with an inline LaTeX formula, \f$\lambda x . x x\f$,
followed by a block formula.

\f[
\begin{aligned}
\text{Let } \Omega & = \omega \omega \\
\text{where } \omega & = \lambda x . x x
\end{aligned}
\f]

renders as:

Here is a sentence with an inline LaTeX formula, $\lambda x . x x$, followed by a block formula.

\[ \begin{aligned} \text{Let } \Omega & = \omega \omega \\ \text{where } \omega & = \lambda x . x x \end{aligned} \]

Attention
The LaTeX examples throughout these pages assume that examples.sty has been installed in your environment as described in README.md.

See us.rader.usingdoxygen.Pythagoras for an example of a contrived context in which documenting algorithms with mathematical formulas can be useful. Embedded LaTeX functionality as well as output to PDF require that appropriate external packages be installed, e.g. texlive on Linux or MiKTeX on Windows.

Graphviz

Doxygen can create simple UML-like diagrams describing your classes and their relationships automatically. us.rader.usingdoxygen.Pythagoras implements the vacuous us.rader.usingdoxygen.Base interface to demonstrate this feature. See us.rader.tt.formula.Expression for a more realistically complex example.

This features requires that you have Graphviz installed in your build environment.

Unlike the embedded PlantUML diagram shown above, the class, object and collaboration diagrams created directly by Doxygen will be kept in sync with your source code automatically.

All of this needs to be enabled via settings in Doxyfile.

If you do have Graphiz installed you can also include custom diagrams in your documentation comment blocks in a fashion similar to that described for PlantUML, above. For example:

\dot
digraph {

rankdir=LR

a -> { b c }
{ b c } -> d

}
\enddot

renders as:

dot_inline_dotgraph_2.png

Quoting Source Files

Neither last nor least, you can extract snippets of source code to display in generated documentation, as in:

\snippet Pythagoras.java Calculate the Hypotenuse

which renders as:

/**
* Calculate the hypotenuse of a right triangle whose legs are of lengths
* `leg1` and `leg2`.
*
* This returns \f$\sqrt{ b^2 + c^2 }\f$ where \f$a\f$ is `b` and \f$c\f$ is
* `b`.
*
* @param leg1
* One leg's length
*
* @param leg2
* The other leg's length
*
* @return The hypotenuse
*
* @throws IllegalArgumentException
* Thrown if either `leg1` or `leg2` is less than or equal to 0.0
*/
public static double calculateHypotenuse(final double leg1, final double leg2) {
if (leg1 <= 0.0) {
throw new IllegalArgumentException("a must be positive");
}
if (leg2 <= 0.0) {
throw new IllegalArgumentException("b must be positive");
}
return Math.sqrt(leg1 * leg1 + leg2 * leg2);
}

or entire source files, as in:

\include Pythagoras.java

which renders as:

/*
* Copyright 2016 Kirk Rader
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package us.rader.usingdoxygen;
/**
* Permutations of the Pythagorean theorem.
*
* The basic theorem is:
*
* \f[
* a = \sqrt{ b^2 + c^2 }
* \f]
*
* where \f$a\f$ is the hypotenuse of a right triangle and \f$b\f$, \f$c\f$ are
* its legs (the sides which form a 90&deg; angle).
*
* @see #calculateHypotenuse
* @see #calculateLeg
*/
public final class Pythagoras implements Base {
/**
* Hidden constructor for utility class.
*/
private Pythagoras() {
throw new IllegalStateException("do not instantiate utilit classes");
}
// ! [Calculate the Hypotenuse]
/**
* Calculate the hypotenuse of a right triangle whose legs are of lengths
* `leg1` and `leg2`.
*
* This returns \f$\sqrt{ b^2 + c^2 }\f$ where \f$a\f$ is `b` and \f$c\f$ is
* `b`.
*
* @param leg1
* One leg's length
*
* @param leg2
* The other leg's length
*
* @return The hypotenuse
*
* @throws IllegalArgumentException
* Thrown if either `leg1` or `leg2` is less than or equal to 0.0
*/
public static double calculateHypotenuse(final double leg1, final double leg2) {
if (leg1 <= 0.0) {
throw new IllegalArgumentException("a must be positive");
}
if (leg2 <= 0.0) {
throw new IllegalArgumentException("b must be positive");
}
return Math.sqrt(leg1 * leg1 + leg2 * leg2);
}
// ! [Calculate the Hypotenuse]
// ! [Calculate the Other Leg]
/**
* Calculate the length of the remaining leg of a right triangle given the
* length of one leg and its hypotenuse.
*
* This returns \f$\sqrt{ a^2 - b^2 }\f$ where \f$a\f$ is `hypotenuse` and
* \f$b\f$ is `b`.
*
* @param leg
* One leg's length
*
* @param hypotenuse
* The length of the hypotenuse
*
* @return The length of the other leg
*
* @throws IllegalArgumentException
* Thrown if either `leg` is less than or equal to 0.0 or
* `hypotenuse` is than or equal to `leg`
*/
public static double calculateLeg(final double leg,
final double hypotenuse) {
if (leg <= 0.0) {
throw new IllegalArgumentException("l must be positive");
}
if (hypotenuse <= leg) {
throw new IllegalArgumentException("h must be greater than l");
}
return Math.sqrt(hypotenuse * hypotenuse - leg * leg);
}
// ! [Calculate the Other Leg]
}

Since both the \snippet and \include directives read the actual source files, such coding examples in generated documentation automatically stay in sync as your code evolves over time. The behavior of \snippet and similar directives require that corresponding labels be embedded as comments in the source files to mark the range of lines to extract.

Summary

Doxygen brings multi-platform, cross-language support for generating rich documentation from source code. It can be used as direct replacement for javadoc and similar facilities in .NET based languages like C#.

Attention
It is worth emphasizing that you do not need to use any of Doxygen's features or special syntax to take advantage of Doxygen. If you have a body of Java code with simple javadoc comment blocks, Doxygen will produce documentation in a variety of formats, including HTML and PDF. Over time, you can start introducing more sophisticated, richly formatted documentation features as the opportunity and need arises.

As an extended example, here is the source code for this page, itself, by way of the \verbinclude ("verbatim include") directive:

// -*- Java -*-

/*
 * Copyright 2016 Kirk Rader
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*!
\page doxygen Using Doxygen

\brief Documenting Java code using Doxygen.

\tableofcontents

\section sc-doxygen-overview Overview

This documentation was generated from Java sources using
[Doxygen](http://www.stack.nl/~dimitri/doxygen/index.html). See
<http://www.stack.nl/~dimitri/doxygen/index.html>.

Doxygen generates richly formatted output in a variety of formats from
javadoc-style comment blocks in a number of programming languages. For example,
simply by adding a _Doxyfile_ configuration file to your source files, you can
generate both HTML and PDF output from Java code with no other changes -- unlike
the native javadoc processor which only supports HTML output.

\section sc-doxygen-basic-formatting Basic Formatting

Doxygen goes beyond the native javadoc process in supporting richer content
using a simpler syntax. For example, you can use
[Markdown](https://daringfireball.net/projects/markdown/) syntax rather than
embedded HTML for things like font styles, hyperlinks etc. For example:

\verbatim
- _italics_
- **bold face**
- `monospaced text`
- [Markdown](https://daringfireball.net/projects/markdown/)
\endverbatim

renders as:

- _italics_
- **bold face**
- `monospaced text`
- [Markdown](https://daringfireball.net/projects/markdown/)

Overall, this results in far more legible code when reading the javadoc comment
blocks directly in the source files than embedding the equivalent HTML tags.

\section sc-doxygen-plantuml PlantUML

With additional external configuration, you can embed
[PlantUML](http://plantuml.com/) diagrams directly in your javadoc comment
blocks. For example:

\verbatim
@startuml
participant client as A
participant service as B
participant backend as C
A -> B: request
activate B
B -> B: validate
opt valid
 B -> C: process
 C -> B: result
end
B -> A: response
deactivate B
@enduml
\endverbatim

renders as:

@startuml
participant client as A
participant service as B
participant backend as C
A -> B: request
activate B
B -> B: validate
opt valid
 B -> C: process
 C -> B: result
end
B -> A: response
deactivate B
@enduml

This requires that the location of the PlantUML JAR file be specified in your
_Doxyfile_. This project's configuration files can be used as a template. In
particular, this project's
[pom.xml](https://gitlab.com/parasaurolophus/examples/blob/master/pom.xml) and
[Doxyfile](https://gitlab.com/parasaurolophus/examples/blob/master/Doxyfile) are
designed to work together such that `mvn install` will pass the artifact id,
version number and other build-time variables to Doxygen which will then place
the generated documentation in a subdirectory of the standard Maven _target_
directory. Also, this project's _Doxyfile_ assumes that a "system" environment
variable named `PLANTUML_JAR` contains the absolute path of the PlantUML JAR
file.

\attention Using an environment variable rather than a hard-coded path in
_Doxyfile_ makes the build portable between development environments and build
platforms but requires external configuration of the build environment. This can
be mitigated using techniques like Maven _profiles_ but at the cost that you can
then only invoke `doxygen` through the use of build scripts rather than directly
at the command line.

\section sc-doxygen-latex LaTeX

You can embed [LaTeX](https://latex-project.org/) formulas both inline or as
block equations. For example:

\verbatim
Here is a sentence with an inline LaTeX formula, \f$\lambda x . x x\f$,
followed by a block formula.

\f[
\begin{aligned}
\text{Let } \Omega & = \omega \omega \\
\text{where } \omega & = \lambda x . x x
\end{aligned}
\f]
\endverbatim

renders as:

Here is a sentence with an inline LaTeX formula, \f$\lambda x . x x\f$,
followed by a block formula.

\f[
\begin{aligned}
\text{Let } \Omega & = \omega \omega \\
\text{where } \omega & = \lambda x . x x
\end{aligned}
\f]

\attention The _LaTeX_ examples throughout these pages assume that
_examples.sty_ has been installed in your environment as described in
\ref a-examples-sty "README.md".

See us.rader.usingdoxygen.Pythagoras for an example of a contrived context in
which documenting algorithms with mathematical formulas can be useful. Embedded
LaTeX functionality as well as output to PDF require that appropriate external
packages be installed, e.g. [texlive](https://www.tug.org/texlive/) on Linux or
[MiKTeX](http://miktex.org/) on Windows.

\section sc-doxygen-graphviz Graphviz

Doxygen can create simple UML-like diagrams describing your classes and their
relationships automatically. us.rader.usingdoxygen.Pythagoras implements the
vacuous us.rader.usingdoxygen.Base interface to demonstrate this feature. See
us.rader.tt.formula.Expression for a more realistically complex example.

This features requires that you have [Graphviz](http://www.graphviz.org/)
installed in your build environment.

Unlike the embedded PlantUML diagram shown \ref sc-doxygen-plantuml "above", the
class, object and collaboration diagrams created directly by Doxygen will be
kept in sync with your source code automatically.

All of this needs to be enabled via settings in _Doxyfile_.

If you do have Graphiz installed you can also include custom diagrams in your
documentation comment blocks in a fashion similar to that described for
PlantUML, \ref sc-doxygen-plantuml "above". For example:

\verbatim
\dot
digraph {

rankdir=LR

a -> { b c }
{ b c } -> d

}
\enddot
\endverbatim

renders as:

\dot
digraph {

rankdir=LR

a -> { b c }
{ b c } -> d

}
\enddot

\section sc-doxygen-snippets Quoting Source Files

Neither last nor least, you can extract snippets of source code to display in
generated documentation, as in:

\verbatim
\snippet Pythagoras.java Calculate the Hypotenuse
\endverbatim

which renders as:

\snippet Pythagoras.java Calculate the Hypotenuse

or entire source files, as in:

\verbatim
\include Pythagoras.java
\endverbatim

which renders as:

\include Pythagoras.java

Since both the `\snippet` and `\include` directives read the actual source
files, such coding examples in generated documentation automatically stay in
sync as your code evolves over time. The behavior of `\snippet` and similar
directives require that corresponding labels be embedded as comments in the
source files to mark the range of lines to extract.

\section sc-doxygen-summary Summary

Doxygen brings multi-platform, cross-language support for generating rich
documentation from source code. It can be used as direct replacement for javadoc
and similar facilities in .NET based languages like C#.

\attention It is worth emphasizing that you do not need to use any of Doxygen's
features or special syntax to take advantage of Doxygen. If you have a body of
Java code with simple javadoc comment blocks, Doxygen will produce documentation
in a variety of formats, including HTML and PDF. Over time, you can start
introducing more sophisticated, richly formatted documentation features as the
opportunity and need arises.

As an extended example, here is the source code for this page, itself, by way of
the `\verbinclude` (\"verbatim include\") directive:

\verbinclude using-doxygen/src/main/java/us/rader/usingdoxygen/page.dox
*/