1. ##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.
2. Doxygen is a tool that can generate project documentation in html, pdf or Latex from code comments formatted with Doxygen markup syntax. The generated documentation makes easier to navigate and understand the code as it may contain all public functions, classes, namespaces, enumerations, side notes and code examples.

C++ Reference Material
Getting Started with Doxygen

Doxygen is a popular tool to document your code, i.e. It is a “documentation system.” Doxygen can be used to generate code for a variety of languages, including Java and C. In this class we will use it extensively for the C projects. Birds-eye view of how Doxygen works There are two main steps in using Doxygen. Doxygen will create a folder called 'docs/apidocs' in your root PALISADE directory. If you go to the 'html' folder there and open up index.html, you will access the HTML version of the documentation. Add 'c:/doxygen/bin' (or whatever path was used during the installation) to the System PATH variable to run 'doxygen' without providing the full.

What is doxygen?

If by any chance you already know what the javadoc tool does for you when writing Java programs, then the easiest way to describe doxygen in the current context is to say that doxygen is to C++ as javadoc is to Java.

If that analogy means nothing to you, then we should say that doxygen is a software utility that recognizes comments within C++ code that have a certain form, and uses them to produce a collection of HTML files containing the information in those comments. For this to be useful, of course, that information should be documentation for the surrounding source code, and this then allows the developer to place that documentation within the source code being documented. This in turn gives the developer much quicker access to the documentation and provides a greater incentive to keep the documentation up to date.

Some doxygen syntax

The first thing to note about the doxygen utility program is that it ignores C++ comments having either of the two usual forms(// .. or /* .. Scar tissue guitar pro. */).

But .. there are two kinds of special comments recognized (and processed) by doxygen:

1. Comments that start with a /** delimiter and end with a */ delimiter.
2. Comments that start with a /**< delimiter and end with a */ delimiter.

Here's the difference between the two: Use the first one if you want to place the comment before the thing you are commenting, but use the second one if you want to place the comment after the thing you are commenting.

The content of a comment having either of these syntactical forms might be just some text (one or two sentences describing whatever is being commented, for example), or some text like that plus some other text marked by special markers called tags, which we discuss below.

For example, here is a doxygen comment:

Doxygen Tags

A doxygen tag is a keyword preceded by the @ symbol. Tags are used inside a doxygen comment to document special parts of the source code (such as a function return type or a function parameter), or to designate additional information (such as author and version number) that you wish to appear as part of the documentation. Text identified by tags is formatted in special ways by doxygen in its HTML output files.

Here is a list of some of the most frequently used doxygen tags:

The tags in the first column above are used for documenting an individual file, or a project, while those in the second column are used for documenting a function.

Some other useful doxygen notes:

1. The dash or hyphen (-) is used to denote a list item, which will be a bulleted item by default, but if you wish to have your list items automatically numbered, use -# instead.
2. Putting a period on a line by itself will terminate a list, if you line it up with the beginning of the list items in the list that you wish terminated. Each - or -# is placed in front of the item it identifies, is followed by a blank space, and is aligned with all the other similar items for the same list. Lists can also be nested. If a second list is nested inside a first list, the items in the second list should be indented with respect to the items in the first list.
3. Many ordinary HTML tags can also be used (<b></b> to make a word bold, for example).
4. The doxygen tool produces HTML files, and because of the way whitespace is treated in HTML you may from time to time have to 'force' line breaks in your HTML output files. You can do this in several ways, depending on the situation. Sometimes leaving a blank line in the input does the trick. You can also use the HTML <br> tag. Somewhat counter intuitively (if you are familiar with HTML), you can also use a n character in your doxygen comments.

An example

A short, and incomplete, example of doxygen documentation is provided in the source code of the sample file doxygen_example.cpp. For a more complete example, check out the documentation for the instructor-supplied utilities package as you continue to use it. You will also find some additional doxygen comments in some of the sample code used to illustrate our C++ programming style conventions under 'Rules + Guidelines: Coding Style'

In the short example given above, look for the above-mentioned doxygen comments and tags, as well as some HTML tags, and then study the corresponding HTML output to see the effect of each tag. This you can do by clicking on html which will take you to the index.html file in the html subdirectory produced from this program by the doxygen tool.

How to produce HTML documentation files from source code files containing doxygen comments

When the doxygen tool processes one or more input source code files, it produces, by default, in the current working directory, a subdirectory named html, which contains all the HTML files that document that source code, according to the doxygen comments contained in the source code. The starting point for browsing this documentation, as you might expect, is the file index.html.

For the above example, to produce the html directory and all the files in it, you just have to put the two files doxygen_example.cpp and the doxygen configuration file doxyconfig in the directory where you want the html directory to appear, and then enter this command:

The doxygen configuration file for any source code file or project can have any name you like. However, it will generally be convenient to give a configuration file for a given source code file or a given project a name that shows its connection with that file or project. If you look at the configuration file for the example you can easily see that for a different project you will want to change the values of PROJECT_NAME, PROJECT_NUMBER and INPUT, but you can probably leave the other parameter values set as they are. Note that INPUT contains a whitespace separated list of all files that you want doxygen to process.

On-Line References

1. Doxygen home page You may get all the detailed information you need, as well as the latest version of doxygen itself from this site.
2. You also have a very good example of doxygen at work in the HTML documentation for the C++ utilities package. You should know where that is and be referring to it frequently!

Remarks

This section provides an overview of what doxygen is, and why a developer might want to use it.

It should also mention any large subjects within doxygen, and link out to the related topics. Since the Documentation for doxygen is new, you may need to create initial versions of those related topics.

Commenting your code

There are several ways to mark a comment block as a detailed description, so that this comment block is parsed by Doxygen and added as a description of the following code item to the documentation. The first and most common one are C style comments with an extra asterisk in the comment start sequence, e.g.:

The next alternative is to use the Qt style and add an exclamation mark (!) after the opening sequence of a C-style comment block:

Doxygen Markdown

A third alternative is to use a block of at least two C++ comment lines, where each line starts with an additional slash or an exclamation mark:

or

Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:

Note the 2 slashes to end the normal comment block and start a special comment block.

To structure and fomat the generated documentation, Doxygen provides a large number (> 170) of special commands. All commands in the documentation start with a backslash () or an at-sign (@).

For example

is equivalent to

For the brief description there are also several possibilities:

One could use the brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.

If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line.

And finally here an example for a full documentation of a function with doxygen: Merge excel to word 2 decimals.

source and more info on the Doxygen homepage

Installation or Setup

Detailed instructions on getting doxygen set up or installed.