how to generate doxygen documentation

Dariusz Zyzański

Open-source and Linux enthusiast

Doxygen C++ documentation for complete beginners

9 minute read

Table of contents

Introduction, arch linux, manjaro, debian, ubuntu, what should be documented, the structure of a doxygen comment, doxygen commands, ide configuration, file encoding, generating the documentation, troubleshooting.

At the university, we had to write a project in C++. Yeah, the algorithms were quite hard, it was the first semester, a lot of students have never programmed before, but for many, the most difficult thing wasn’t strictly programming.

It was Doxygen. We were required to document our programs using the Doxygen format, generate PDFs, and send them along with the source code. In order to help my colleagues, I had decided to write a guide in Markdown, upload it to GitHub Gist, and voilà! Documentation wasn’t an issue anymore.

The original guide is written in Polish. I’m presenting to you an English translation, extended and improved. I hope it’ll help you document your code!

Installing the required software

• Go to https://www.doxygen.nl/download.html .

• Install Doxygen with default settings.
• Go to https://miktex.org/download .

Graphviz (optional)

Graphviz will enable Doxygen to generate more advanced diagrams and graphs. If you don’t need that, you don’t need to install Graphviz.

• Go to https://graphviz.org/download/ .

On Linux, installation is much easier. All you need to do is to enter a few commands into the terminal. You don’t need to dig around the web for the installers.

qt5-base is required for Doxywizard.

You may also need other packages, like texlive-lang . Please refer to the Arch Wiki .

This metapackage should contain everything you need. In case it doesn’t, look at the source package texlive-base and install additional components selectively. If you don’t mind downloading and installing gigabytes of TeX packages, you can also choose to install texlive-full .

This metapackage should contain everything you need. In case it doesn’t, refer to the Fedora Docs and either install missing packages selectively or install a set of packages (like texlive-scheme-full ).

You shouldn’t need to install Graphviz manually under Fedora, as Doxygen has a dependency on it. But, in case someone needs the command anyway:

Documenting the code

For C++, you should document the following stuff:

• classes and structures
• enum entries
• variable declarations
• function declarations

Generally, the comment should be placed right above the block of code. There are two exceptions:

They should be documented at the beginning of the file.

• variables and enum entries

If they require just a short comment, you should document them inline.

There are multiple styles of Doxygen comments. I’ll describe my style here. If you want to check out some other styles, refer to the Doxygen Manual .

Normal comment

The Javadoc comment style looks like this:

Inline comment

Inline comments look like this:

Knowing the structure of a comment isn’t enough to write the documentation. You need some commands to tell Doxygen what exactly you’re describing.

The most important commands are:

• @file [filename]

Tells Doxygen to generate documentation for this file.

This is very important for projects that aren’t purely object-oriented! Without documenting each file with @file , Doxygen won’t generate the docs for your methods, global variables, and possibly other stuff.

• @brief [short description]

A short description of the whole code fragment. Depending on your settings, this may:

• need to be at most one line long
• need to end with a dot

The safest thing to do is to do both.

• @param [parameter name] [description]

A description of the function parameter. All parameters should be described.

• @return [description of the returned value]

A description of the returned value. Naturally, void functions don’t need that.

• @copyright [a copyright notice]

A copyright notice. Usually used together with @file .

• no command ( @details )

When you need to write a detailed description, there’s no need for a command, you just need to make an empty line before it. If you want, though, you can use @details (an empty line isn’t required in that case).

Your IDE should help you with the general structure.

Visual Studio Code should work out of the box. You can also install the Doxygen Documentation Generator plugin. It will automatically generate some boilerplate for you.

There are also some extensions, like DoxygenComments . Check them out - they’ll generate the boilerplate for you.

Before you generate the docs, you should make sure that your source code is saved with UTF-8 encoding. Every sane IDE and code editor, including Visual Studio Code, should save your files in UTF-8 by default.

Unfortunately, that’s not true for Visual Studio, which uses regional encoding by default! I don’t know what Microsoft was thinking, but now, you have to make sure that your files are saved with UTF-8.

Alternatively, you can change the encoding in Doxywizard.

Setting UTF-8 as the default in Visual Studio

Visual Studio supports EditorConfig files. Making sure that every file is saved with UTF-8 is pretty simple:

• Create a file named .editorconfig in the root folder of your project: [*] charset = utf-8
• Save the file. Restart Visual Studio.

Changing the encoding in Doxywizard

See this page for the list of possible encodings. For example, if your files are encoded in codepage 1250, configure your Doxyfile like this (‘Expert’ -> ‘Project’):

Converting your files to UTF-8

Before you defer to the manual solution, try to do that automatically. Refer to this Stack Overflow question. Remember to backup your project!

• Click ‘OK’. Your file should be converted to UTF-8. Don’t forget to convert other files.
• Enter the root directory of your project.
• Create a folder where the documentation will be generated (like Docs ).
• Launch Doxywizard.

Compiling your documentation

You don’t need to do that if all you need is the HTML. But if you need a PDF file, you need to compile the LaTeX files generated by Doxygen. Fortunately, it should be very simple:

• Enter Docs/latex .
• Run the following command: pdflatex refman.tex
• Check the resulting file, refman.pdf .

If you can’t generate your docs, or there is an issue with them, refer to the troubleshooting section.

You can do everything graphically, but if there’s an error, you may need to open the PowerShell console and run the script manually.

Graphical way

• Run make.bat . You can just double-click on it.

If there’s an issue with your docs, refer to the troubleshooting section. If you can’t generate them, and you can’t see any error message (the terminal window closes automatically), you need to run the script manually with PowerShell. If you can see the error message, you can already go to troubleshooting .

PowerShell way

Press enter.

Now, the terminal window won’t close automatically. You’ll be able to see the error and you can refer to the troubleshooting section.

Unsupported characters

These are errors like this one:

The easiest fix - just remove the unsupported character. For example, I could replace ‘😃’ with ‘:-)’.

National alphabet characters aren’t rendered properly

So, you open the PDF, and something’s wrong… national alphabet characters, like the Polish letters with diacritics (e.g. ą, ę) are either rendered without the diacritics or they are completely skipped!

That’s probably an encoding issue. Refer to File encoding .

Missing TeX packages

That’s mostly a Linux issue, as on Windows, MiKTeX should download all required packages on-the-fly.

If you’re a Linux user, refer to this section .

If you’re a Windows user, make sure that you have an internet connection and check the MiKTeX settings. You’ll find them in the MiKTeX console.

I hope you’ve found my article helpful. In case there’s an error, you have a suggestion, or you just want to talk - you can send me an e-mail. Also, don’t forget that DarkoGNU.eu is open-source, so you can open an issue , submit a pull request , or even start a discussion .

You May Also Enjoy

What is musl is it ready for desktop.

5 minute read

If you’re into open-source, there’s some chance you’ve already heard the term musl. Musl is an implementation of the C standard library, just like the GNU C ...

User-mode Linux: kernel as a process (tutorial)

Imagine that you have a VPS. You want to do something unsafe, e.g. set up a system with major security holes, so that you can test the skills of your “friend...

Documenting Python Programs With Doxygen

Skill Level: Intermediate

Table Of Contents

Introduction, what is needed, background information, installing doxygen, creating a sample python program, creating the doxygen configuration file, running doxygen, viewing the generated documentation.

This tutorial will teach you how to use the Doxygen utility to generate program documentation for your Python based project. A basic understanding of Python programming is expected.

The resources created for this tutorial are available on GitHub for your reference.

• Linux, macOS, Or Windows Based Computer

Doxygen is a utility that generates program documentation from source code. It parses programs written in various programming languages that are annotated with certain commenting styles. The generated documentation will include summary descriptions for almost all of the elements and members defined in your program. It can also include additional information based on special annotations used within the comments. Doxygen can generate documentation in a variety of formats, e.g. HTML, LaTex, XML, RTF, etc. which makes it appealing to a wide audience. I will be focusing on HTML in this tutorial.

I am using a macOS based computer. If you are using a Linux or Windows computer, the vast majority of this tutorial should still apply, however, some minor changes may be necessary.

If you need assistance with your particular setup, post a question in the comments section below and I, or someone else, can try to help you.

Please see the Doxygen downloads page for general installation instructions for your computer platform. The program binaries for the latest release are about half way down the page.

Since I am using a Mac and do not plan to use the GUI front end, I chose an alternative approach and installed Doxygen from the command line via the Homebrew package manager using the following command.

This installed the doxygen executable into the /usr/local/bin directory on my Mac.

Once the program is installed, either make sure that it can be found within your executable path or prepend the full directory path upon execution. Test that it is installed correctly by executing the following command within a terminal or command window that will simply print its version number.

My version shows the following.

In order to generate source code based documentation using Doxygen, we first need to have source code for it to use. We will create a main program, named doxygen_example.py , and a module, named sensors.py , that will be used by the program. This program, along with the associated module, are not meant to actually do anything useful. They merely provide an example of how to comment your source code so that it can be properly parsed by the Doxygen utility. It contains various types of elements (e.g. constants, variables, functions, classes, modules, etc.) that are common in Python programs.

Create a project directory named MyDoxygenExample and go into that directory. Create a src directory under the project directory and go into that directory as well. This is where we will place our source code. Create and save a Python program named doxygen_example.py within this src directory with the code shown below.

Likewise, create and save a Python module named sensors.py with its code shown below.

In my example code, the exclamation point ( ! ) at the beginning of a docstring or the double number sign ( ## ) at the beginning of a comment block tell Doxygen to parse this area. The at sign ( @ ) represents a command, e.g. @param or @section , that provides the Doxygen parser with further instruction.

Along with generating documentation for the general programming elements, Doxygen also provides a facility for including additional documentation that will be shown on the main page of the documentation or on the pages for the individual files. These are enabled with the @mainpage and @file commands respectively. We will see how this works when we view the generated documentation later.

A variety of comment formatting styles are supported by Doxygen. I chose what I believe to be the most clear and concise styles for this example that are also compatible with the standard Python docstring conventions. Please feel free to view and play around with other supported styles shown within the Doxygen manual . However, you might want to wait until the end of this tutorial before making any changes.

Now run the program to make sure we did not accidentally introduce any errors. The first line of the main program, doxygen_example.py , contains a shebang ( #! ) statement allowing us to run the program as a command line script. To do so, make the program an executable with

and then execute it.

Alternatively, you could just run it with the Python interpreter.

The program output should look like the following.

Again, this is just an example program. Don’t pay too much attention to what it is actually doing, just how the comments are formatted for the various types of programming elements or pages.

Now let’s create a documentation directory where our Doxygen based configuration and generated documentation will be located. Create a doxygen directory within the project directory parallel to the src directory. Alternatively, you could name the documentation directory as docs , as many people prefer, but I choose to name it based on the documentation generator in case I choose to use additional generators as well.

In order to effectively parse the source code to generate our project documentation, Doxygen requires the use of a configuration file. This file, named Doxyfile by default, is where we set up our project specific information and tell Doxygen how to parse the Python code.

Within a terminal or command window, go into the documentation directory and create a default Doxygen configuration file by running the following command.

This will create a Doxyfile configuration file within the current directory. If you look at the file, each configurable setting is prepended by a comment letting us know what the setting does, how changing it will affect your generated documentation, and the default value. This is a nice touch by the Doxygen team. These settings are also listed in the Doxygen manual .

Now we need to edit the Doxyfile file to enter our project specifics. The first change we want to make is to tell Doxygen the name of our project. This is accomplished by changing the following line, around line 35, from

This will be the title of the project within our generated documentation. This is where you change the title to something that makes sense for your project.

The next one enables Doxygen to utilize Javadoc style briefs which allows us to write comments such as

for describing code elements. Although this particular style is not explicitly being used in my example, it is a useful option to have enabled. To do so, change the line, around line 198, from

To optimize the generated documentation for Java and Python based source code, change the line around 280 from

Next, tell Doxygen to generally extract all elements found in the source code. Change the line around 464 from

Note, the EXTRACT_PRIVATE and EXTRACT_STATIC settings can also be set to YES if you want to include private class members and static file members in the generated documentation as well.

Next up is around line 566. Change

This setting will hide the scope name that is typically prepended to element names contained within that scope. This is being done to make the documentation for some pages look a bit cleaner.

To sort the elements in alphabetical order instead of when they are declared, change the line, around 613, from

Now, we need to tell Doxygen where to find the Python source code by making the following change, around line 826.

Finally, since we are not planning to generate LaTex based documentation, we will suppress it by changing the line, around 1716, from

These are my preferred options. OPTIMIZE_OUTPUT_JAVA and INPUT are really the only settings required for generating Python based documentation with Doxygen. The others provide enhancements to the extraction and readability of the generated documentation in my opinion.

Save your updated Doxyfile configuration file when complete.

Now that the configuration file is updated, run Doxygen to generate the HTML based documentation for our Python based project. In the same directory as the Doxyfile , run the Doxygen executable.

Doxygen will print to the screen the various tasks it is performing while running. It will also print any warnings or errors that occurred during execution. Once complete, you should see that it created an html directory that contains all of your HTML based documentation that it generated for your project.

Load the index.html file located within the html directory into your browser. This is the main project page and displays all of the information, separated by sections, that we specified within the comment block containing the @mainpage command in our doxygen_example.py program. It also shows the project title we specified in the configuration file.

Across the top of the page, under the project title, you will see the Main Page , Packages , Classes , and Files tabs with their accompanying pull down menus. These tabs and menus will contain all of the documentation generated for your project.

The Packages tab will provide a list, with brief descriptions and associated links, for the various packages (files/modules) that Doxygen found in your project. The detailed information for each package, seen by clicking the associated link, e.g. doxygen_example , is very similar to the information found under the Files tab. One major difference though is that the latter will also show the extra documentation that was added in the comment blocks containing the explicit @file command.

The Classes tab provides a list of the classes included in our project. The Sensor and TempSensor classes are both shown here under the sensors module. Clicking on TempSensor will show us the detailed information of the TempSensor class along with the members defined in that class.

Take a peak at the other menu options to get an idea of how the documentation is structured. This would also be a good time to look at some of the other options available in the configuration file. Play around with changing some of those settings and rerunning Doxygen to see how they change the resulting documentation. You could also play around with trying some of the other supported commenting styles mentioned earlier. You might find something you prefer more than my general setup.

In this tutorial, we learned how to generate project documentation from source code using the Doxygen utility for a Python based project. Generously commenting your code and generating the source code documentation is a great way to provide both a high level architectural overview and the low level implementation details of a project. Not only does it provide others the means to more easily understand your code, it can also help the original programmer who hasn’t worked on that code in a while.

We barely touched the surface of all the things you can do with Doxygen. If you are interested in learning more, please see the Doxygen manual along with reviewing the multitude of settings comments found within the Doxygen configuration file, Doxyfile , itself.

The Python project and Doxygen configuration file used for this tutorial are available on GitHub .

Thank you for joining me in this journey and I hope you enjoyed the experience. Please feel free to share your thoughts in the comments section below.

About the author

John Woolsey

John is an electrical engineer who loves science, math, and technology and teaching it to others even more.   He knew he wanted to work with electronics from an early age, building his first robot when he was in 8th grade. His first computer was a Timex/Sinclair 2068 followed by the Tandy 1000 TL (aka really old stuff).   He put himself through college (The University of Texas at Austin) by working at Motorola where he worked for many years afterward in the Semiconductor Products Sector in Research and Development.   John started developing mobile app software in 2010 for himself and for other companies. He has also taught programming to kids for summer school and enjoyed years of judging kids science projects at the Austin Energy Regional Science Festival.   Electronics, software, and teaching all culminate in his new venture to learn, make, and teach others via the Woolsey Workshop website.

13 Comments

Hi there, Noticed, the class/function documentation is AFTER the definition. This makes reading the code utterly and ridiculously difficult. Does this HAVE to be like that? Could it be like in c++, before the function definition? Python is horrifically difficult to read anyway with it’s indentation based layout. Don’t need to add to the confusion with these descriptions.

Since this article uses Python, I chose to use the standard Python way of documentation using docstrings, which put descriptions below their respective objects, within my example source code. Like you, this seems backwards to me as well since I am more accustomed to the traditional methods used by older languages. However, you are not stuck having to use that approach. Instead of the Python standard “”” docstrings after the object, you can use ## comments before the object. Please see the Comment blocks in Python section in the Doxygen manual for an example.

I have access to a large set of python test ( + 1500 files) ( to test an API) I was used to Doxygen back in the days (prior doxy-wizard, around <2000), in C/C++, IMHO, a most useful feature is the call-caller graph.

In my searches, I found some descriptive that mentioned that Doxygen have "difficulties" with those graph for Python.

You may know if the call-caller graph is operational… ( I don't want to use many hours to only conclude that the graph is not working.)

I’m sorry, I don’t know, but I hope you find your answer. If you do, please let us know.

I think I originally misunderstood your question.

I looked into the call-caller graphs for Python this morning and found that they do work, but not as extensively as the C/C++ side. Specifically, I see the call and caller graphs for functions, but the file dependency graphs are not displayed for Python.

I enabled them by turning on the following options: HAVE_DOT, CALL_GRAPH, and CALLER_GRAPH.

Hope that helps.

Hello, is it normal that in the documentation of the Public Member Functions of the classes, the parameters are in a white rectangle with the apparent doxygen commands (@param, @return)? Is there a way to fix this so that the tipography is the same everywhere?

Unfortunately, that is normal due to the way I compromised and mixed using standard Python docstrings with Doxygen style commenting in this tutorial.

I really like using Doxygen for C/C++ programs, but it may not be the best choice for Python programs. The standard Python documentation strategy uses docstrings (“””) which do not play well with Doxygen. If you abandon the use of docstrings altogether, you can make the Doxygen documentation look much more like that generated for C/C++ by using only the Doxygen style comments (##) in your source code as shown in the Comment blocks in Python section of the Doxygen Manual. This is a valid choice and is probably what you were hoping to achieve.

Most people writing Python programs use Sphinx to generate their documentation as it uses the standard docstring comments. However, I find the Sphinx tool a bit more cumbersome to use than Doxygen. I have a tutorial for Documenting Python Programs With Sphinx as well if you are interested.

Thanks! It has helped me starting …

You are welcome.

Thanks, John, and have a nice day

You are very welcome. You have a nice day as well.

Thanks, John. I have a good starting point now.

You are very welcome. I am glad you found it helpful.

Leave a Comment X

Save my name, email, and website in this browser for the next time I comment.

Notify me of follow-up comments by email.

Notify me of new posts by email.

This site uses Akismet to reduce spam. Learn how your comment data is processed .

Getting started

Doxygen information flow

Step 1: Creating a configuration file

Step 2: running doxygen.

Step 3: Documenting the sources

• Place a special documentation block in front of the declaration or definition of the member, class or namespace. For file, class and namespace members it is also allowed to place the documention directly after the member. See section Special documentation blocks to learn more about special documentation blocks.
• Place a special documentation block somewhere else (another file or another location) and put a structural command in the documentation block. A structural command links a documentation block to a certain entity that can be documented (e.g. a member, class, namespace or file). See section Documentation at other places to learn more about structural commands.
• The special commands inside the documentation are executed. See section Special Commands for an overview of all commands.
• If a line starts with some whitespace followed by one or more asterisks ( * ) and then optionally more whitespace, then all whitespace and asterisks are removed.
• All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
• Links are created for words corresponding to documented classes.
• Links to members are created when certain patterns are found in the text. See section Automatic link generation for more information on how the automatic link generation works.

Document your source code with Doxygen on Linux

Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0

When trying to familiarize yourself with someone else's project, you usually appreciate the comments left behind that help you understand the meaning of their code. In the same way, whenever you are programming, whether for yourself or for others, it is good practice to comment your own code. All programming languages offer a special syntax to mark a word, a line, or a whole section as a comment. Those areas are then ignored by the compiler or interpreter when the source code is processed. 

Comments don't take the place of documentation, but there is a way to use your comments to produce documentation easily. Meet  Doxygen , an open source tool for generating HTML or LaTeX documentation based on comments in the code. Doxygen enables you to provide a comprehensive overview of the structure of your code without additional effort. While Doxygen is mainly used to document C++, you can use it for many other languages, like C, Objective-C, C#, PHP, Java, Python, and more.

To use Doxygen, you simply comment your source code in a syntax that Doxygen can read. Doxygen then walks through your source files and creates HTML or LaTeX documentation based on those special comments. The C++ example project below will illustrate how the source code is commented and how the documentation is generated from it. The example is available on GitHub , and I will also include references to different sections of the Doxygen manual and documentation .

[ Download now: Doxygen cheat sheet ]

Install Doxygen on Linux

On Fedora, Doxygen is available as a package. Open a terminal and run:

On Debian-based systems, you can install it by running:

Once installed, all you need is a project with Doxygen-compatible comments and a Doxyfile , a configuration file that controls the behavior of Doxygen.

Note: If you stick to the related example project on GitHub, you can omit the next step.

If there is no Doxyfile yet, you can simply let Doxygen generate a standard template. To do so, navigate to the root of your project and run:

The -g stands for generate. You should now notice a newly created file called Doxyfile . You can invoke Doxygen by simply running:

You should now notice two newly created folders:

By default, Doxygen outputs LaTeX-formatted documentation as well as HTML-based documentation. In this article, I will focus only on HTML-based documentation. You can find out more about LaTeX output in the official Doxygen documentation, in the Getting started section.

Double click on html/index.html to open the actual HTML documentation. With a blank configuration, it probably looks like the screenshot below:

(Stephan Avenwedde, CC BY-SA 4.0)

Now it's time to modify the Doxyfile and add some special comments to the source code.

The Doxyfile allows you to define tons of adjustment possibilities, so I will describe only a very small subset. The settings correspond to the Doxyfile of the example project.

Line 35: Project name

Here you can specify the project name, which will be visible in the header line and the browser tab.

Line 47: Project brief description

The brief description will also be shown in the header but in a smaller font.

Line 926: Inclusion of subdirectories

Allow Doxygen to walk recursively through subdirectories to find source and documentation files.

Line 1769: Disable LaTeX output

If you are just interested in the HTML output, you can disable the LaTeX code generation using this switch.

After every change, you can run Doxygen again to check whether your changes have had the desired effect. If you just want to check which modification an existing Doxyfile has, invoke Doxygen with the -x switch:

As with the command diff , Doxygen displays only the differences between the actual Doxyfile and the template.

Special comments

Doxygen reads the sources and checks each file for special comments. Based on those comments and keywords, it builds up the HTML documentation. The anatomy of the special comments can be well explained using the header file of the class ByteStream, as shown in the GitHub example linked above.

I will look at the constructor and destructor as an example:

There are different flavors of formatting a special comment block. I prefer to start the comment in the Qt-style ( /*! ) and add an asterisk ( * ) before each line. The block then ends with an asterisk followed by a forward slash ( */ ). To get an overview of the different style options, refer to the Doxygen manual, in the section Documenting the code .

Comments in Doxygen are divided into two sections, a brief description and a detailed description. Both sections are optional. In the code sample above, the comment block refers to the following line of code, the declaration of a constructor. The sentence behind the @brief will be shown in the compact class overview:

After a blank line (blank lines are treated as paragraph separators), the actual documentation for the constructor begins. With the @param[in/out] keyword, you can mark the arguments passed to the constructor, and Doxygen will make a clear argument list from it:

Note that Doxygen automatically creates a link to the mentioned buffer() and size() method in the comment. In contrast, the comment before the destructor declaration won't have any effect on Doxygen as it is not recognized as a special comment:

Now you have seen 90% of the magic. By using a slightly modified syntax for your comments, you can convert them into special comments that Doxygen can read. Furthermore, by using a few keywords, you can advance the formatting. In addition, Doxygen has some special features, which I will highlight in the following section.

Most of the work is already done via your regular commenting on the source code. But with a few tweaks, you can easily enhance the output of Doxygen.

For advanced formatting, Doxygen supports Markdown syntax and HTML commands. There is a Markdown cheat sheet available in the download section of opensource.com.

Aside from your customized header, you will get a mostly empty page when you open html/index.html . You can add some meaningful content to this empty space by using specific keywords. Because the main page is usually not dedicated to a particular source code file, you can add an ordinary text file containing the content for the main page into the root of your project. You can see this in the example on GitHub. The comments in there produce the following output:

Automatic link generation

As noted above, Doxygen automatically figures out when you are referring to an existing part of the code and creates a link to the related documentation. Be aware that automatic link creation only works if the part you refer to is documented as well.

More information can be found in the official documentation, under Automatic link generation .

The ByteStream class has overloaded stream operators for writing ( << ) and reading ( >> ). In the class overview in the Special comments section above, you can see that the operator declarations are grouped as Writing and Reading . These groups are defined and named in the ByteStream header file.

Grouping is done using a special syntax: You start a group with @{ and end it with }@ . All members inside those marks belong to this group. In the header ByteStream.h it is implemented as follows:

You can find more information about grouping in the Doxygen documentation, under Grouping .

LLVM Support

If you are building with Clang , you can apply the flag -Wdocumentation to the build process to let Clang check your special comments. You can find more information about this feature in the LLVM Users Manual or in Dmitri Gribenko's presentation, both on the Clang website.

Where Doxygen is used

Doxygen was first released in 1997, so it has been already around for some years. Despite its age, many projects use Doxygen to create their documentation. Some examples are NASA's F Prime flight software framework, the image processing library OpenCV , and the package manager RPM . You can also find the Doxygen syntax in other areas, like in the documentation standards of the content management platform Drupal .

A caveat: One drawback of using Doxygen is that it outputs HTML documentation with the look and feel of web pages from the nineties. It is also hard to depict the architecture of meta and template programming using Doxygen. For those cases, you would probably choose Sphinx over Doxygen. Download the Doxygen cheat sheet now.

Comments are closed.

Related content.

Navigation Menu

Search code, repositories, users, issues, pull requests..., provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications You must be signed in to change notification settings

Official doxygen git repository

doxygen/doxygen

Folders and files, repository files navigation.

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D. Doxygen also supports the hardware description language VHDL.

Doxygen can help you in three ways:

• It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, DocBook and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
• You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
• You can also use doxygen for creating normal documentation (as I did for the doxygen user manual and doxygen web-site).

The latest binaries and source of Doxygen can be downloaded from:

• https://www.doxygen.nl/

Doxygen's internal source code documentation

Install: Please read the installation section of the manual ( https://www.doxygen.nl/manual/install.html )

Project stats: https://www.openhub.net/p/doxygen

Issues, bugs, requests, ideas

Use the issue tracker to report bugs.

Mailing Lists

There are three mailing lists:

• [email protected] - Announcement of new releases only
• [email protected] - for doxygen users
• [email protected] - for doxygen developers
• https://sourceforge.net/projects/doxygen/

Source Code

In May 2013, Doxygen moved from subversion to git hosted at GitHub

• https://github.com/doxygen/doxygen

Dimitri van Heesch (doxygen at gmail.com)

Releases 11

Contributors 261.

• Python 11.2%
• JavaScript 0.6%

Version 1.11.0 is now available!   Release date: 20 May 2024

Code Documentation. Automated.

Free, open source, cross-platform.

Doxygen is a widely-used documentation generator tool in software development. It automates the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in formats like HTML and PDF. By simplifying and standardizing the documentation process, Doxygen enhances collaboration and maintenance across diverse programming languages and project scales.

Multiple output formats

Doxygen can generate documentation in various output formats, such as HTML, PDF (via LaTeX), Word (via RTF), and XML.

This flexibility allows developers to choose the format that best suits their needs or integrate the documentation into different systems.

Markdown support in Doxygen allows you to combine the simplicity of Markdown with the powerful features of Doxygen for documenting code.

Next to Markdown, Doxygen supports many commands like \param , \return , \brief , etc., to provide additional information about functions, parameters, and return values.

Doxygen provides robust support for documenting C++ code, recognizing the intricacies of the language and generating comprehensive documentation.

Next to C++, Doxygen also supports C, Python, PHP, Java, C#, Objective-C, Fortran, VHDL, Splice, IDL, and Lex.

Cross-referencing

Doxygen provides cross-referencing capabilities, allowing users to navigate between different parts of the documentation.

Doxygen generates hyperlinks to related elements, making it easy to explore the codebase and understand the relationships between different components.

Doxygen can generate graphical representations of class hierarchies and collaboration diagrams, providing a visual overview of the relationships between classes and functions.

Configuration

Doxygen provides a configuration file (Doxyfile) that allows users to customize the documentation generation process. You can control various settings, such as the output format, file inclusion/exclusion, and more.

Sponsored links (not related to doxygen)

• home cleaning

CLion 2024.1 Help

Doxygen documentation.

Doxygen -style comments can be placed across the source code and used for generating fully-fledged documentation in various formats.

CLion includes the information from doxygen into the Quick Documentation popup Ctrl+Q :

Viewing doxygen documentation

Doxygen-styled information is included in Quick Documentation popup in addition to the type information. To invoke the documentation popup:

Place the caret at the desired symbol or at the @param command of the doxygen comment.

Press Ctrl+Q .

Alternatively, when the checkbox Show quick documentation on hover ( Settings | Editor | General | Other ) is selected, you can just move your mouse pointer over the desired symbol.

If function parameters are documented separately from the function description, CLion will merge all the comments and show you the full function’s signature documentation (the same way as doxygen does when generating the output) :

Creating doxygen comments

To create a doxygen comment from scratch:

Type one of the following symbols: /// , //! , /** or /*! and press Enter .

You will get a stub to fill with the documentation text:

To change the prefix type or to add the @brief tag:

In CLion Classic, go to Settings | Editor | Code Style | C/C++ .

In CLion Nova , go to Languages & Frameworks | C/C++ | Code Generation .

Open the Code Generation tab and scroll down to the Documentation Comments section:

Scroll down to the Documentation Comment Template section:

Reliable rename

While renaming a function or its parameters, the doxygen comments need to be updated accordingly. In case of the Rename refactoring Shift+F6 , CLion updates doxygen comments along with other references.

Typing assistance

Basic typing assistance for doxygen commands is provisioned by CLion auto-complete feature:

Note that not all the commands are available in the completion. Here you can find the list of the commands that are currently unsupported.

Rendered view for doxygen comments

With CLion, doxygen comments can be shown in an easier-to-read format. In this Rendered View mode, items are shown grouped by their tags, while the tags themselves are skipped.

Note the rendered view limitations:

Opening the referenced web pages is not available.

EOL block comments are rendered only if they start the line.

Toggle and configure the rendered view

To turn on the Rendered View mode for all doxygen comments in the current file, select Render All Doc Comments from the context menu in the gutter.

If necessary, select Adjust Font Size from the context menu and change the font size using the slider.

To show all doxygen comments rendered by default, open the Settings dialog ( Ctrl+Alt+S ) , go to Editor | General | Appearance , and select the Render documentation comments checkbox.

To hide the Rendered View gutter icons, select Configure Gutter Icons from the context menu in the gutter and then clear the Documentation comments in-place rendering checkbox on the Settings | Editor | General | Gutter Icons page that opens.

Doxygen comments colors

To configure the colors that are used in doxygen comments, go to Settings | Editor | Color Scheme | C/C++ and open the Comments | Doxygen node:

Doxygen Tutorial: Getting Started Using Doxygen on Windows!

In this tutorial, let us learn about the Documentation software Doxygen and see how to make use of it to make the job of producing documentation more automated and stress-free!

Let us start by looking at what Doxygen is.

What is Doxygen?  Doxygen is a software used to produce documentation of source code written in C, C++, Python, Java, etc. and delivers in various formats like HTML, PDF, etc.

In other words, Doxygen is a software specifically made to fulfill the need for producing and maintaining documentation with as little effort as possible.

That is just the short version of the answer, read my other article for a longer and more informative answer where I try to answer the following questions

• Why you might need to use Doxygen?
• Is Doxygen the right choice for you?
• If no, then what are the alternatives available?
• If yes, then how to get started using Doxygen?

Here is the link again.

Doxygen, What is it? How it works?

In this article, our focus will be on how to get started to actually start using Doxygen.

Step 1: Download and install Doxygen

So head over to the Doxygen official website given in the link below and download the latest release of Doxygen.

Doxygen Download Page

You can opt in for notifications regarding updates using the form shown in the screenshot below

If you scroll a bit down, till you see something like this.

Click on the link highlighted in the red box above to get the software.

If nothing happens after you click, then probably your browser is preventing you from downloading the executable. But don’t worry, just right-click the link and click on “ save link as” to get the software as shown in the screenshot below. (I am using Chrome).

Your browser might now ask you for confirmation whether you wish to download an executable, say yes as shown in the screenshot below and you should be good to go!

On Google’s Chrome Browser you will see something like this on the bottom right corner. Click on the “down arrow icon” then click “Keep” and Doxygen should start downloading.

Then go through the usual installation steps to finish installing Doxygen on your Windows PC. I recommend keeping the default settings while doing so.

Once that is done you should be able to launch the Doxygen software from the windows start menu. The software should be under the name “Doxywizard” as shown in the screenshot below.

Once you open that app, you must see something like shown in the screenshot below.

If you got till here, congratulations, you have finished the first step of installing Doxygen software on your PC!

Step 2: Learn How to Document the code using Doxygen

Doxygen works by taking the comments which are specifically formatted according to Doxygen’s pre-agreed syntax.

Doxygen calls these special syntaxes as “Tags”. Let us see some of those before we actually get into using them!

Doxygen tags and symbols to use in your comments

Doxygen supports several methods for incorporating documentation inside the comments. The 2 simplest methods to include in C source code are

 … comments…

/// Comments.

Note the extra asterisk (*) in line 1 of the first option and extra slash symbol(/), (i.e. in C we just need 2 slashes for a comment line) These syntaxes are used to tell the Doxygen parser that it is documentation and it needs to be extracted.

The above 2 syntaxes must be placed just above  an entity  so that the Doxygen parser can associate the comments to that particular  entity.

What is an entity in Doxygen?  An entity can be a global variable, a structure declaration, enum declaration, or a function.

The entities and tags are implemented in code as shown in the screenshot above.

The Doxygen generated documentation from the code above will look like this

Next, let’s look at the documentation of parameters. Here another special Doxygen syntax is used which is the @ syntax.

Doxygen calls these structural commands.   There are several of them and the most useful ones are the following.

Let us see how you can use Doxygen entities to document your source code at various levels.

Step 2.1: File headers

File headers contain detailed description about a given file. This must be present at the top of every file which needs documentation. If there is no file header then Doxygen will not produce documentation for that file.

File headers look like this

Just use the Doxygen “structural command” @file followed by the file’s name, to tell Doxygen that you want this file to be included in the documentation generation process. You can also add some description about the file to be shown in the Documentation as shown in the screenshot below.

As you can see, the file name and description are placed on the documentation page generated for this example file main.c

Next lets us have a look at how to properly document functions and their arguments.

Step 2.2: Function Documentation

As we have seen above any function in a file can be documented by simply adding a Doxygen styled comment just above the function.

Next lets see how to describe the arguments and return values. Consider the following 2 functions

The syntax used in the parameter description is the following

@param[in/out] <variable name> <variable description>

Since the variable name radius is obvious to the reader of the code, I did not add the description. Please have a look at my other article “ How To Use The Power Of Comments In Your Code The Right Way? ” for guidelines on commenting.

The output produced by doxygen using the syntaxes above will look like this

Step 2.3: Global Variables Documentation

We have seen how to document modules(files) and functions inside a given file, next let us see how to use doxygen to document other entities like global variable, constants etc.

As we have already seen in the beginning of step 2, a simple one line Doxygen style comment is enough to document a global variable. But some developers don’t like the idea of adding comments between each and every line of code in the global variable declaration section. To get around that problem Doxygen provides a second way of creating comments as shown in the screenshot below.

If you look at the code, you may have noticed that instead of keeping the comments on top of the entity  I have kept it at the right-hand side of the macro definition.

Also instead of “/// “

I have used “///< “

This style can also be used to document more complex entities like structs and constants/macros as shown in the screenshots below.

The documentation produced by Doxygen will look something like this.

On clicking the “More..” in the screenshot above, you can get more documentation on the members of the structure like this

Step 2.4: Doxygen Pages

On Doxygen, we can also produce documentation pages which are not connected to any of our source files. These pages can be used to describe the project or individual modules.

Read the below sections to learn more about how to add pages in doxygen.

These are the normal pages. These will show in the first level of pages on your left-hand side of the tree view. In a later section of this article, I have shown you how to enable “TreeView”  which I think is better than the default view for C documentation.

The structural command to use for a Doxygen page is @page as shown in the markdown file below

After running it through Doxygen the final output will look like this

These pages will not be on the first level, rather it will be placed under another page.

The structural command to use for a Doxygen sub-page is @subpage. This @subpage should be used on the module’s page to which the given page is a sub-page to like this.

The markdown file for the subpage will look like this

As you can see in the above picture, the Doxygen output has added the sub-page “ Sub module Nam e” under the page “ Module Name ” on the tree-view at the left-hand side and added a link to it on our page.

The sub-page itself is an ordinary page and it looks like as it is shown in the image below.

I generally avoid sections and subsections as it increases the complexity of the documentation process. I like doing them with Markdown formatting options instead (even if that will make it hard to interlink a section with another one). I leave it up to you to decide for yourself if you need them in your particular project or not.

Step 3: Produce Documentation

Step 3.1: configure doxygen.

There are several settings that can be configured to fine tune the output to just the way we want it to look like.

For example consider the example below on how to create different levels of descriptions by tuning the settings of Doxygen.

Brief vs Detailed Descriptions in Doxygen

By default, the descriptions produced by are not divided into “Brief” and “Detailed”

Consider the code below.

Here the description of the entity 2 function has been expanded to have multiple lines. Now running doxygen with default settings will produce a page like this.

As you can see above, there is no documentation next to entity2 function like entity1 variable has.

By tuning the settings of Doxygen (I have explained exactly how to do this in the following section) you can make Doxygen parser to take the first sentence of the comment to be the brief description and the remaining sentences to be detailed description.

Once you have downloaded and installed Doxygen successfully, you can find an app Doxywizard. This will looks something like the below screenshot

So click on Expert->Project

2 simple tweaks that can be done in this section is shown in the image below (the red rectangles show the changes made).

The option FULL_PATH_NAMES has been unchecked so that the final output doesn’t include the entire path name like “ C:/User/user_name/Desktop?project_directory/sub_directory/file_name “. Instead, we can get the output to start from the root directory of the project itself. In the above case, the output HTML will only show “ sub_directory/file_name “

All these tweaks and configurations will be stored in a file named Doxyfile on your project folder.

This is just one of many configuration parameters available in Doxygen. To see a more comprehensive example of what more you can configure, I suggest reading the article below where I have explained how exactly to configure the Doxyfile to produce documentation for C programs.

Complete Guide On Using Doxygen To Document C Source Code..!!

I have also included the Doxyfile I have used for that project as a Download with that article so do check that out!

Now that we have covered how to configure Doxygen let us go ahead and see how you can run this program.

Step 3.2: Run Doxygen

You can run doxygen from the Doxywizard as follows

• Select the source code directory in the Doxywizard’s main window
• Go to the run tab
• click “Run doxygen”
• click “Show HTML output”

You can view the generated documentation in your project folder. There you can see that doxygen has generated a folder named “html” inside which lies all your documentation that you needed!

Open the “html” folder and double click on the “index.html” file to see all the documentation that has been generated by Doxygen for you!

I will stop here, hope you found this article useful!

Feel free to share this article with your friends and colleagues!

Here are some other articles that might interest you!

Related Articles

How to use the power of comments in your code the right way, c: macro function vs regular function vs inline functions.

Doxygen: Generate Documentation from Source Code

Chen Weixiang @ Jun 12, 2016 | TAG: Tools

This article introduces the usage of Doxygen, and generates data structure for Linux kernel project.

What’s Doxygen?

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.

Doxygen can help you in three ways:

It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files . There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

You can configure doxygen to extract the code structure from undocumented source files . This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

You can also use doxygen for creating normal documentation .

Doxygen is developed under Mac OS X and Linux, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available.

Install Doxygen

Run the following command to install Doxygen:

You can also install doxygen from source code if you like to do so, refer to Doxygen Installation .

Usage of Doxygen

According to Getting started , the following figure shows the relation between the tools and the flow of information between them:

And here is the steps of using Doxygen:

• Step 0: Check if doxygen supports your programming language
• Step 1: Creating a configuration file
• Step 2: Running doxygen
• Step 3: Documenting the sources

Extract Data Structure for Linux Kernel

Create configuration file.

Edit the configuration file linux-kernel-config and change the values of the following TAGs. Refer to Doxygen Configuration for more explanation of each TAG.

Run Doxygen in Linux Kernel

Create output directory by command:

Then, run Doxygen in directory ~/linux/kernel/ to check the data structure in Linux kernel:

Open Output in Browser

The output is generated in output directory ~/linux_doxygen/output . Check the output by Firefox:

For instance, here is the data structure of struct worker :

• Doxygen Offical Site
• Doxygen Articles
• Doxygen Manual
• Doxygen Installation
• Doxygen Configuration
• Doxygen FAQ
• Other Tools

How Effective Team Documentation Boosts Productivity: Tips and Tools for Success

Why Team Documentation is Important

Team documentation is the backbone of effective collaboration, serving as the repository of knowledge and processes that guide a team’s efforts.

With good documentation, all team members are aligned, informed, and equipped to perform their tasks efficiently.

By documenting key information, teams can avoid miscommunication, prevent knowledge loss, and maintain continuity, even when team members change.

The Value of Documentation in a Team Setting

• Knowledge Sharing : It facilitates the sharing of information, ensuring that all team members have access to the same knowledge base.
• Training and Onboarding : New team members can quickly get up to speed with comprehensive onboarding manuals and process documents.
• Consistency : Standardized documentation ensures that processes and procedures are followed consistently across the team.
• Decision Making : Well-documented information helps in making informed decisions, reducing the risk of errors and inefficiencies.
• Historical Record : Documentation serves as a historical record, preserving the rationale behind decisions and changes for future reference.

The Impact of Effective Team Documentation on Productivity and Efficiency

Effective team documentation can significantly enhance productivity and efficiency by:

• Reducing Redundancies : Clear documentation helps avoid duplication of efforts by providing precise guidelines and instructions.
• Minimizing Interruptions : Team members can find answers to their questions in the documentation, reducing the need to interrupt colleagues.
• Streamlining Processes : Documented processes and workflows ensure smooth operations and quick resolution of issues.
• Enhancing Collaboration : With accessible documentation, team members can collaborate more effectively, knowing they are all on the same page.
• Facilitating Remote Work : Documentation becomes even more critical in remote or distributed teams, providing a virtual hub of information.

Types of Team Documentation

Internal communication documents.

These documents include meeting notes, memos, and internal reports that keep team members informed about ongoing activities and decisions.

Process Documentation

This type outlines the steps and procedures necessary to complete specific tasks or processes, ensuring that everyone follows the same method.

Project Documentation

Project documentation includes project plans, timelines, roles, responsibilities, and progress reports, which are essential for managing and tracking project activities.

User Documentation

User documentation provides end-users with instructions on how to use a product or service, including manuals, guides, and troubleshooting documents.

How To Create Good Team Documentation

1. establish a central source of truth.

Centralize all documentation in a single, easily accessible location to ensure that team members can always find the most up-to-date information.

Use knowledge base software or documentation software to manage this.

• Top knowledge base software recommendations
• Top documentation software recommendations

2. Creating Clear and Concise Documentation

Ensure that all documents are written in a clear and concise manner, using simple language and avoiding unnecessary jargon.

This is particularly important for technical documentation and user manuals.

3. Regularly Update and Maintain Documentation

Regularly review and update company documentation to reflect any changes in processes, tools, or team structures, ensuring that it remains relevant and accurate. Utilize a documentation tool with version control to manage updates efficiently.

4. Collaborate Through Documentation Tools

Use collaboration features in your documentation tools to allow team members to contribute to and review documentation in real-time, fostering a sense of ownership and participation.

5. Make Documentation Accessibility for All Team Members

Make sure that documentation is easily accessible to all team members, regardless of their location or role, by using cloud-based platforms and ensuring mobile compatibility. Documentation software with robust search capabilities can aid in this.

Try These Tools for Team Documentation

Document collaboration software.

Tools like Google Docs and Microsoft Word Online allow multiple team members to work on the same document simultaneously, track changes, and leave comments.

Project Management Apps

Project management tools like Asana or Monday help teams document tasks, projects, and workflows, ensuring that everyone knows their responsibilities and deadlines.

Knowledge Base Platforms

Platforms like Tettra , Confluence , and Notion provide a centralized place for creating, storing, and organizing team knowledge and documentation.

• Compare Confluence & Tettra side-by-side

Content Management Systems

CMS tools like WordPress and SharePoint help teams manage and publish documents and content, making it easy to update and distribute information.

Challenges and Solutions for Team Documentation

Challenge 1: overcoming barriers to entry in using documentation tools.

Solution : Provide training and support to ensure that all team members are comfortable using the documentation tools. Tools with intuitive interfaces and robust support materials, like a help center, can ease this process.

Challenge 2: Addressing Issues of Disorganized Communication and Poor Documentation

Solution : Implement standardized templates and establish clear guidelines for documenting information to ensure consistency and organization. Utilize technical documentation tools to maintain high standards.

Challenge 3: Managing Version Control and Outdated Documentation

Solution : Use tools with version control features and establish a regular review process to keep documentation up-to-date. This is crucial for software documentation where changes in source code must be reflected accurately.

Challenge 4: Automate the Documentation Process for Efficiency

Solution : Automate repetitive documentation tasks where possible and encourage team members to contribute to documentation as part of their regular workflow. Incorporate documentation software that integrates with existing systems and processes.

Specific Documentation Considerations for Software Teams

For software development teams, specialized documentation is critical. This includes:

• Code Documentation : Ensure source code is well-documented to facilitate understanding and maintenance. Use tools like Javadoc for Java or Doxygen for C++.
• API Documentation : Clear and detailed API documentation is essential for developers integrating with your software. Utilize an API documentation tool to streamline this process.
• System Documentation : Comprehensive system documentation helps maintain and scale the software system.
• User Manuals and Product Documentation : Provide detailed user manuals and product documentation to help users effectively use your software.

By following best practices and leveraging the right tools, teams can create and maintain documentation that serves as a valuable resource for all members.

Overcoming common challenges and ensuring that documentation is clear, concise, and accessible will ultimately lead to a more efficient and cohesive team environment.

For software developers, integrating documentation into the software development lifecycle is particularly important, ensuring that both internal and external documentation supports the overall goals of the project.

How Tettra Helps With Your Team Documentation

Tettra is an AI-powered knowledge management system that helps you curate important company information into a knowledge base, use it to answer repetitive questions in Slack and MS Teams and keep it up-to-date, organized, and complete with automation.

• Centralized Knowledge Base : Store all team documentation in one accessible location.
• Integrations: Seamlessly integrates with tools like Slack, Google Docs, and Github for streamlined collaboration.
• Templates : Use standardized templates for consistent documentation across the team.
• Search Functionality : Powerful search features make it easy to find information quickly.
• Collaborative Editing : Multiple team members can contribute and edit documents in real-time.
• Documentation Requests : Allows team members to request documentation, ensuring all necessary information is covered.
• Permission Control : Manage access levels to keep sensitive information secure.

With Tettra, you’ll get: 

• AI-powered knowledge base software to document answers
• Q&A workflow to capture questions
• Knowledge management features to keep content up to date.

Start with Tettra for free today.

Start building your knowledge base today.

Fewer repetitive questions for you and faster answers for your team.

We guarantee you’ll be hooked.