DOXYGEN Is it a good tool?

Been debating on this myself and figured this was the best place to ask and get input from other programmers. Is doxygen a good tool to use and worth learning? I can completely see where it is useful for if you are building libraries and APIs, but is it just as beneficial if you are doing other projects?
closed account (Dy7SLyTq)
thats the comment thing right?
Doxygen is awesome. It's not perfect but it is extremely useful. Even if you don't use it to generate HTML/LaTeX documentation, you should still get into the habit of commenting your header files (comments in source files are distracting IMO) with Doxygen comments. You should be commenting your header files to describe every entity therein already, and you should be using Doxygen comments in particular because the tags give your comments structure; compare
1
2
// Make snafucated.
bool make_snafucated(snafucatable& object);

and
1
2
3
4
5
/// Snafucates an object.
/// \param object The object to be snafucated. Must be snafucatable.
/// \return If the object was successfully snafucated, true is returned;
/// otherwise, false is returned.
bool make_snafucated(snafucatable& object);

The latter comment has structure which is useful on a larger scale. And then there's the obvious benefit that, if you want, you can extract all your documentation to HTML files so that any other programmer who gets involved in your project can simply read the documentation listing.

Of course, if you're not writing a library or an API, you still need to write user documentation for the program - source code documentation is not very useful there. And you will probably want to write a tutorial of some kind even if you are writing an API or library, because oftentimes looking at source code references is not enough to tell you how to use a library. So, again, it's not perfect and it doesn't cover every use-case, but it is still extremely useful. Unless you're writing a proprietary program and you know no-one else will ever have source code access, you're going to have to document your source code - so why do it by hand?
Last edited on
Well I'll definitely take time to learn Doxygen. You never know when you may end up writing a library or API for something.
I also find it very useful when I start to work on a new codebase. If Doxygen documention isn't already available, I run Doxygen against the code to see what's up (after tweaking the config file to ensure all the useful graphs are generated.) Even without tagging, Doxygen can extract a lot of useful info.

If you're using Doxygen in this way, you should also install GraphViz, which is used to generate the various graphs. (Doxygen does have basic graphics support, but it's better if you use GraphViz.)

Graphviz - Graph Visualization Software
http://www.graphviz.org/

Doxygen can also work with Mscgen, a tool to generate sequence charts.

Mscgen
http://www.mcternan.me.uk/mscgen/

Andy

PS Checking one of the Doxygen files I have to hand, I have made the following tweaks to the one you get when you run Doxygen with the -g switch to generate a fresh config file. Mostly aimed at finding out what's going on in the code, rather than producing pretty documentation.

PROJECT_NAME
PROJECT_NUMBER
INPUT
OUTPUT_DIRECTORY
WARN_LOGFILE
IMAGE_PATH

are all set to suitable values

FILE_PATTERNS          = *.h *.cpp *.c *.dox

I use .dox for Doxygen markup only files. Sometimes you also need .hpp, etc (I tend to adjust this suit rather than use the default.)

BUILTIN_STL_SUPPORT    = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
SHOW_DIRECTORIES       = YES
RECURSIVE              = YES
SOURCE_BROWSER         = YES
INLINE_SOURCES         = NO
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
GENERATE_TREEVIEW      = YES
GENERATE_LATEX         = NO
HAVE_DOT               = YES
UML_LOOK               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

And if I have a web server to hand, sometimes

SEARCHENGINE           = NO

If I'm running Doxygen on a large codebase, I either trim this set down, or generate Doxygen for a subtree of the project at a time.
Last edited on
closed account (Dy7SLyTq)
so i could run doxygen on a doxygen script?
so i could run doxygen on a doxygen script?

If by doxygen script you mean a doxygen config file, I don't think so. Though as Doxygen is open source, you could always teach it how to do so.

If you mean a file containing the same mark-up as used for C++, etc files, then yes.

Andy

e.g. (the tags still have to go inside a comment block)

//! \mainpage Welcome to Foobar Project
//!
//! \section contents Contents
//! \li \ref intro_sec
//! \li \ref design_sec
//! \li \ref testing_sec
//!
//! \section intro_sec Introduction
//! Welcome to the Foobar Project.
//!
//! Foobar is working towards the realization of a multi-paradigm foobar by
//! leveraging the synergies in a holistic way than embraces a novel convergent
//! paradigm shift.\p
//!
//! The foobar application uses a proactive feedback mechanism to bar all foo.\p
//!
//! \section design_sec Design
//!
//! Foobar will leverage a holostic melange of object-orientated, functional,
//! proceedural, etc working exclusively with the console and the system()
//! function (in color.)
//!
//! "Only a madman will use C++" (mis-quote of Douglas Crockford.)
//|
//! \image png "foobar main classes.png" "Foobar Design" width=10cm
//!
//! \subsection module_subsec Modules
//!
//! Foo
//|
//! An term used for unimportant variables in programming when the programmer is
//! too lazy to think of an actual name. The origin of such word is described in
//! detail in RFC 3092.
//!
//! Bar
//!
//! The other default variable used in programmer's slang.
//!
//! \section testing_sec Testing
//!
//! TODO
//!


* Definitions of foo and bar from http://www.urbandictionary.com
* Buzz words gleaned from cumulative, proactive googling.
* Quote sort-of from Douglas Crockford, based on a number of random comments about the quote, which is actually:

The approach I finally settled on was language subsetting, which was not something I ever expected. It's been said only a madman would use all of C++. It's also been said only a madman would use C++.
Last edited on
I'll have to give graphviz a try. Installed it on crunchbang and will do searches to learn to use it later.
Topic archived. No new replies allowed.