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. Jul 29, 2008 Run doxygen in the shell prompt as doxygen Doxyfile (or with whatever file name you’ve chosen for the configuration file). Doxygen issues several messages before it finally produces the documentation in Hypertext Markup Language (HTML) and Latex formats (the default).
Introduction
Throught this course you will be working on big software projects and an important part of any large project is documentation. Documentation is especially important in group projects, like many of the projects in this class. Imagine how useful a browsable index will be when your partner is asleep and you're trying to figure out his/her code. In order to ensure that your source code has adequate documentation, we will be requiring that your code be fully documented using doxygen, a documentation system for C similar to JavaDoc. This document serves as a brief overview of doxygen and the features you will use on a regular basis. For a more detailed description of doxygen and all of its features visit the doxygen homepage. You can get detailed documentation and information about compiling and installing doxygen on a home system.
There are two types of comments we want in your code. The first kind are comments at the beginning of each file which describes the file and lists things like author and known bugs. The second kind of comments are those that describe your functions and data structures. We want you to put comments on all your functions and data structures. You do not have to comment individual variable instances but are welcome to if you'd like. The rest of this document talks about the doxygen commands that you need for each of the two kinds. First, we'll describe what we expect to see and then talk about the specific commands that you need to use including simple examples. Lastly there will be a larger example showing all of commands together.
Comments for Files
Each file needs to begin with the @file command stating the name of the file. This should be followed by a brief description of the file using the @brief command. If necessary, you can follow this with a more detailed description. Next you should put your name and andrew id, along with your partners name and andrew id, using the @author tag. This needs to be followed with a bugs section with a list of known bugs using the @bug command. If there are no known bugs, explicitly state that using the @bug command.
Comments for Functions and Data Structures
Before each function, data structure, and macro you should put a comment block giving at least a brief description using the @brief command. A brief description will suffice for your data structures but for you macros and functions you will need to use a few more commands. After your description, you should use the @param command to describe all of the parameters to your function. These descriptions should be followed by a description of the return value using the @return command. Note: When we say 'each' function, that is not a strong statement. You can leave out simple helper functions, like a max() macro, so you don't waste time.
You can choose to comment your functions either in the header files where they are declared, in the source files where they are implemented or both. This is a matter of taste. If you put it in the header file, like in the example, then you should be sure to remember to update the comments with the latest details of the implemenation. If you choose to put the comments in both places note that if there is a difference between the two sets of comments, the block at the declaration will superceed the one at the implementation. The long and short of this is that you should not put the comments in both. For assembly files, you can put the comments in the header file where they are declared.
Doxygen Tags
Here is what we expect to see in the non-brief section of the function:
- Anything a user needs to know to decide whether this is the right function for them to use for a given job.
- Usage preconditions: must be called with interrupts disabled, etc.
- Any use of an unusual algorithm (in which case, cite it -- academic format or page title and URL)
- Why the code was written in a non-obvious structure.
- Warnings about how to extend the function without breaking it.
Coding Style / Coding Standards
At some point in your career you may well be required, or at least expected to adhere to an explicit coding standard document. If you are ever present at the inception of a large project, you will have the opportunity to watch the inevitable flame war over tab stops and brace placement. Don't worry--for 15-410, we aren't going to tie you down that much.
However, you should use a consistent and defensible style. It would probably be a good experience for you to read a few coding style documents to see how they differ and how you feel about the differences. When you begin work with your partner on Project 2 you will have an opportunity to discuss this issue. We won't require the two of you to use exactly the same style, but it would probably make sense for style to not vary wildly within a single file. For open source projects (i.e., potentially many authors over many years), one popular approach is for the 'primary author' of each file to set the style (within reason) and other developers to try to emulate that style (again, within reason, but it really is good form for any change you suggest to blend in with the code that's already there).
Here are some coding style documents you may find useful. This purports to be a (the?) Linux kernel coding style document. To the eyes of an old BSD hand, this looks a little cavalier, which is unsurprising. The BSD Kernel Normal Form (KNF) is also worth a look. Many moons ago C programmers inside AT&T put together the Indian Hill C Style guide, which has been updated to yield a generically titled Recommended C Style and Coding Standards guide. Here are Style guides for Google-originated open-source projects, and here are Lester McCann's suggestions 'Toward Developing Good Programming Style'. Of course, they contradict each other and probably every other coding style document on the planet, but you shouldn't let that bother you, and you should be able to detect a common core.
![Doxygen Doxygen](/uploads/1/3/4/9/134901804/800497774.jpg)
You may also wish to consult How NOT to go about a programming assignment by Agustín Cernuda del Río.
What really matters is:
- Modularity
- The scheduler functions are in a file full of scheduler functions and nothing else; each function is coded up once; etc.
- Documentation
- This can be read at multiple levels. For example, people can read a short file to find out if your program is right for them; can read about a module or package to see if they want to steal it for their own programs; can read about a function to decide whether they need to read the code, etc.
- Maintainability
- Including basic things such as essentially never putting a hardwired constant such as 1128 into a file, and never using it twice, and never ever putting 1127 into your code because it's 1128 - 1. But you knew all that from 15-213, right? Since you asked, the right way to handle 1128 would be
(GREY << COLOR_SHIFT) | (ELEPHANT << ANIMAL_SHIFT) | 16 /* tons */ - Dead Code
- There are two very different kinds of 'dead code' which students tend to turn in. One kind is 'debug code' which was briefly useful but never will be again, stuff like
// printf('!!!! joe = %dn', 4 * i / 0);
orint threadstatus = THR_RUNNING; // THR_RUNNING|128
or// if (threadid 17) MAGIC_BREAK;
Realistically, even if something like that helped you track down a bug once, you wouldn't re-activate it to find the next one. Since this code will never be run again, leaving it around can't do anything except distract and slow down your audience. Don't turn it in.
In the other direction, occasional assert()s are fine. In fact, sensibly done, they actually help document the code. See the section on asserts.
Overall, if debug code is genuinely likely to be useful to readers or maintainers, that argues in favor of keeping it, but the vast majority of what gets stuck in temporarily is just noise, and should be deleted. - Asserts
- Asserts are statements that check that the assumptions that were made in your program are not violated. For example, let's say you have a variable
*nodeptr
. If, by design,nodeptr
can never point toNULL
, then a statement likeASSERT (nodeptr);
or, in the Linux idiom,if (!nodeptr)
BUG();
is a way of verifying that this assumption is not violated. This is useful in two ways. Firstly, it documents your assumption. Secondly, in future, if anyone modifying your code violates this assumption, (s)he is informed of this early, rather than having to discover this through a debugging session. Hardcore performance evangelists will argue that such code will almost never be executed, and that the extra conditional statement just serves to affect the branch prediction accuracy. People with such concerns should look at thelikely()
andunlikely()
preprocessor macros in the Linux kernel and the associated gcc builtin function__builtin_expect()
. However, people who don't have measurable performance problems should probably avoid littering their code with cryptic incantations without actual benefit.
Descriptions of Commands
Go here: http://www.stack.nl/~dimitri/doxygen/commands.html for descriptions of the commands mentioned.
Putting it All Together
![Doxygen Doxygen](/uploads/1/3/4/9/134901804/203165433.jpg)
Here is a short example showing all the elements together. This is an old version of the Project 1 starter code, presented in order to demonstrate doxygen (i.e., don't cut and paste this code into a current project!). As a note, README.dox is a text file with a single block of C-style comments in it.
- Doxygen Commenting
- It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in ) 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. You 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 even `abuse' doxygen for creating normal documentation (as I did for this manual).
- Section Installation discusses how to download, compile and install doxygen for your platform.
- Section Getting started tells you how to generate your first piece of documentation quickly.
- Section Documenting the code demonstrates the various ways that code can be documented.
- Section Lists show various ways to create lists.
- Section Grouping shows how to group things together.
- Section Including formulas shows how to insert formulas in the documentation.
- Section Graphs and diagrams describes the diagrams and graphs that doxygen can generate.
- Section Preprocessing explains how doxygen deals with macro definitions.
- Section Automatic link generation shows how to put links to files, classes, and members in the documentation.
- Section Output Formats shows how to generate the various output formats supported by doxygen.
- Section Searching shows various ways to search in the HTML documentation.
- Section Customizing the output explains how you can customize the output generated by doxygen.
- Section Custom Commands show how to define and use custom commands in your comments.
- Section Linking to external documentation explains how to let doxygen create links to externally generated documentation.
- Section Frequently Asked Questions gives answers to frequently asked questions.
- Section Troubleshooting tells you what to do when you have problems.
- Section Features presents an overview of what doxygen can do.
- Section Doxygen usage shows how to use the
doxygen
program. - Section Doxytag usage shows how to use the
doxytag
program. - Section Doxywizard usage shows how to use the
doxywizard
program. - Section Installdox usage shows how to use the
installdox
script that is generated by doxygen if you use tag files. - Section Configuration shows how to fine-tune doxygen, so it generates the documentation you want.
- Section Special Commands shows an overview of the special commands that can be used within the documentation.
- Section HTML Commands shows an overview of the HTML commands that can be used within the documentation.
- Section XML Commands shows an overview of the C# style XML commands that can be used within the documentation.
- Section Doxygen's Internals gives a global overview of how doxygen is internally structured.
- Section Perl Module output format documentation shows how to use the PerlMod output.
- Section Internationalization explains how to add support for new output languages.
- implementing features,
- fixing bugs,
- providing priority help in answering questions.
- Malte Zöckler and Roland Wunderling, authors of DOC++. The first version of doxygen borrowed some code of an old version of DOC++. Although I have rewritten practically all code since then, DOC++ has still given me a good start in writing doxygen.
- All people at Qt Software, for creating a beautiful GUI Toolkit (which is very useful as a Windows/Unix platform abstraction layer :-)
- My brother Frank for rendering the logos.
- Harm van der Heijden for adding HTML help support.
- Wouter Slegers of Your Creative Solutions for registering the www.doxygen.org domain.
- Parker Waechter for adding the RTF output generator.
- Joerg Baumann, for adding conditional documentation blocks, PDF links, and the configuration generator.
- Tim Mensch for adding the todo command.
- Christian Hammond for redesigning the web-site.
- Ken Wong for providing the HTML tree view code.
- Talin for adding support for C# style comments with XML markup.
- Petr Prikryl for coordinating the internationalization support. All language maintainers for providing translations into many languages.
- The band Porcupine Tree for providing hours of great music to listen to while coding.
- many, many others for suggestions, patches and bug reports.
It can help you in three ways:
Doxygen is developed under Linux and Mac OS X, 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.
This manual is divided into three parts, each of which is divided into several sections.
The first part forms a user manual:
The second part forms a reference manual:
The third part provides information for developers:
Doxygen license
Copyright © 1997-2011 by Dimitri van Heesch.
Permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU General Public License is hereby granted. No representations are made about the suitability of this software for any purpose. It is provided 'as is' without express or implied warranty. See the GNU General Public License for more details.
Documents produced by doxygen are derivative works derived from the input used in their production; they are not affected by this license.
User examples
Doxygen supports a number of output formats where HTML is the most popular one. I've gathered some nice examples of real-life projects using doxygen.
Doxygen Dependency Graph
These are part of a larger list of projects that use doxygen. If you know other projects, let me know and I'll add them.
Commercial Support
I'm currently investigating the possibilities of providing commercial support for doxygen. The forms of support I'm thinking of are:
To get a better understanding of the feasibility, please let me know if you have a need for this type (or another type) of doxygen related commercial support.
Future work
Although doxygen is successfully used by large number of companies and open source projects already, there is always room for improvement.
Doxygen Download Windows
You can submit enhancement requests in the bug tracker. Make sure the severity of the bug report is set to 'enhancement'.
Acknowledgements
Thanks go to: