KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #cli #react #mcp

doxygen-example

★ 56 Open GitHub ↗

Small example of how to use Doxygen

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Doxygen Example

Doxygen is a tool that parses source code, finds specially-formatted comments,
and produces nice-looking documentation files out of them. This repository is
set up as an example that shows how Doxygen can be used.

For more information about how Doxygen works, see the [official Doxygen
website](https://www.doxygen.nl/index.html).

The Doxygen output for the project is available
[here](https://nullromo.github.io/doxygen-example/).

## This Repository

There are a few example C++ files in the `src/` directory. To run the code,
there is a `run.sh` file, which compiles the code and runs the result. An
`autoformat.sh` script is also provided for completeness.

## How to Install Doxygen

### WSL Installation Instructions

If you are using a Windows computer, you should be using Windows Subsystem for
Linux (WSL). There is no reason not to use it. It is vastly superior to the
available Windows command prompt and to alternatives like GitBash. On top of
that, you should be using WSL-TTY. If you use these, installing doxygen is as
simple as following the steps below.

Doxygen can be installed with apt.

```
sudo apt-get install doxygen
```

In order for the pretty source tree graphs to be generated, you also need to
install graphviz.

```
sudo apt install graphviz
```

Now you should be able to run Doxygen from the command line.

```
doxygen --version
```

### Windows Installation Instructions

If for some reason you are not using WSL, you can follow these steps to install
Doxygen.

1. Download and install Doxygen for Windows from the Doxygen website.
2. Add Doxygen to the Windows PATH.
3. Install the latest stable release of graphviz.
4. Add graphviz to the Windows PATH.
5. Modify the `Doxyfile`'s `DOT_PATH` variable to point to the path of the
   graphviz executable.
6. Run doxygen.

## How to Use Doxygen

There is a file called `Doxyfile` that controls how Doxygen will run. A new
`Doxyfile` can be generated by using `doxygen -g <filename>` (leave the
filename blank normally). This configuration file can be modified to change how
Doxygen runs, and each project has its own `Doxyfile`.

To run doxygen, simply navigate to the project directory and run `doxygen`. It
will look for source files, parse them, and generate output. For this project,
a new folder called `generated-docs` will be created, but with the default
configuration, the output will simply appear in the same folder as the
`Doxyfile`. Inside the output folder or directly in the root folder, there will
be an `html` folder, with a file called `index.html` in it. Open the
`index.html` file with a web browser to view the documentation.

## How to Deploy Doxygen to Gitlab

After each push, Gitlab scans your repository for a file called
`.gitlab-ci.yml`. If that file is present, it will read the file and check that
the file specifies a valid CI pipeline. If it is valid, then Gitlab looks for
an available "runner." Runners can be other computers on the network, but in
this case the runner is a docker container within the gitlab server virtual
machine. Once a runner is available, Gitlab assigns a build for the project to
the runner. The runner uses the pipeline from the `.gitlab-ci.yml`
configuration file to know what actions to take. Part of that pipeline can
include exporting build artifacts (like Doxygen html files or firmware .hex
files).

For our Doxygen deploys, the configuration file will specify that `doxygen` is
to be run, and that the built files are to be copied to the correct location
for deployment. So in short, including the `.gitlab-ci.yml` will cause your
deployed documents to update every time you push.

## How to Comment for Doxygen

Doxygen comments start with `/**` and end with `*/`, like this:

```c
/**
 * Doxygen comments go here.
 *
 * The extra asterisks to the left are not required, but they are nice to have
 * visually.
 */
void exampleFunction(void);
```

A comment block like this will be recognized by Doxygen and will end up in the
documentation. These blocks can contain differnt types of keywords, such as
`\brief`, `\param`, and `\return`. An example C function is shown below using
these. More examples can be found in the `src/` directory of this repository.

```c
/**
 * \brief Adds two numbers.
 *
 * This function takes two numbers, adds them, and then returns the result.
 * 
 * \param x The first number to add.
 * \param y The second number to add.
 * \return The sum of the two numbers.
 */
int add(int x, int y) {
    return x + y;
}
```

This Doxygen comment is complete, because it contains a `\brief` description of
the function, it contains a detailed description beneath that, and it contains
`\param` and `\return` descriptions for all its parameters and its return
value.

## Commenting for C/C++ with Header Files

In general, high-level comments (for documentation) should go in the header
file, not the corresponding C file. Comments belong with *declarations*, not
with *definitions*. For C++ classes, the `.hpp` file should be full of member
declarations and Doxygen comments, while the corresponding `.cpp` file should
consist mostly of just code.

Inline comments that are embedded inside of a function's body should of course
go in the function definition itself (in the `.cpp` file). Functions that do
not appear in the header file should be given Doxygen comments in the C file.

In short, there should never be 2 Doxygen comments for the same member, and
putting the Doxygen comments in header files is preferred.

## Grouping Members

You can also group members that go together. For example, you may have 5
constants that would require the same documentation:

```c
#define MEW2KING 1
#define ARMADA 2
#define HUNGRYBOX 3
#define MANGO 4
#define PPMD 5
```

Instead of writing out the same documentation comment for each of these
members, you can create a group like this:

```c
/**
 * @{ \name Five Gods constants.
 */
/**
 * \brief Five Gods constants.
 *
 * These five constants represent the five gods.
 */
#define MEW2KING 1
#define ARMADA 2
#define HUNGRYBOX 3
#define MANGO 4
#define PPMD 5
/**
 * @}
 */
```

If the `DISTRIBUTE_GROUP_DOC` option is set to "YES" in the `Doxyfile`, then
the documentation comment will be applied to all the member in the group. The
`\name` tag also shows up as a heading over the group members.

## This Repository's `Doxyfile`

The `Doxyfile` in this repository was generated using `doxygen -g`, and then
edited in the following way:

```
Line 35:
PROJECT_NAME           = "Kyle's Doxygen Test"
Line 47:
PROJECT_BRIEF          = "This is just a test of Doxygen"
Line 54:
PROJECT_LOGO           = "./DiConIcon.ico"
Line 61:
OUTPUT_DIRECTORY       = "generated-docs"
Line 438:
EXTRACT_ALL            = YES
Line 363:
DISTRIBUTE_GROUP_DOC   = YES
Line 444:
EXTRACT_PRIVATE        = YES
Line 450:
EXTRACT_PACKAGE        = YES
Line 456:
EXTRACT_STATIC         = YES
Line 481:
EXTRACT_ANON_NSPACES   = YES
Line 759:
WARN_NO_PARAMDOC       = YES
Line 867:
RECURSIVE              = YES
Line 876:
EXCLUDE                = README.md
Line 998:
SOURCE_BROWSER         = YES
Line 1004:
INLINE_SOURCES         = YES
Line 1017:
REFERENCED_BY_RELATION = YES
Line 1023:
REFERENCES_RELATION    = YES
Line 1031:
REFERENCES_LINK_SOURCE = NO
Line 2334:
CALL_GRAPH             = YES
Line 2346:
CALLER_GRAPH           = YES
```

**NOTE**: The `DiConIcon.ico` file needs to be accessible at the given path (in
this case in the root of the repository) in order for it to show up in the
documentation pages.

## Tips/Rules
- Always use a `\param` tag for every parameter.
- Always use a `\return` tag is the function returns a non-void value.
- Always include a `\brief` description in addition to a long description.
- Always put a Doxygen comment on every class, function, or macro in the source
  code.

doxygen-example

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README