Automatic source code documentation - Doxygen

[munch]

Hi Guys,

I've looked at the source a couple of times, but never got that far with it, due to the extreme lack of documentation. Here's some help in the form of a free tool, Doxygen, which we use at work a fair bit. It makes things *much* easier.

Doxygen creates html documentation from the source code and has a diagram drawing add-on, which draws class diagrams (showing the full inheritance tree), collaboration diagrams (showing direct inheritance plus what classes use what other classes), call dependency graphs, include graphs etc.

It works pretty well out of the box (you can expect to be up and running in under an hour), but a little bit of configuring makes it really nice (a lot of the diagrams and nice features are switched off by default).

It automatically pulls any doxygen header comments out and puts them in the documentation against the class/method/field they apply to -really neat. But even without the comments (Spring is a bit short of comments) the documentation it produces is very useful.

The thing that makes it great is all the hyperlinks. You can click on any box in any diagram and it'll take you to the documentation for that item. It also links you in to a syntax highlighted version of the source code (this is one of the features which is switched off by default - don't ask me why!), which again is full of iinks back to the documentation - making it very easy to traverse around the code and find out what on earth is going on.

It basically makes the code a lot more accessible.

You can download Doxygen from here: http://www.doxygen.org

The add in which you'll need to get it to draw the diagrams (again off by default) can be downloaded from here:
http://www.graphviz.org/

I'm happy to upload a configuration file with all the sensible stuff switched on if people would like me to. The default settings really are a bit mad! There is a wizard with excellent tool tips to help you get set up though, but some of the options you really want switched on are easy to miss when you first start using the tool.

What would be really great is if the Spring website could host the doxygen documentation for the code to amke it accessible to all - Who would I ask about that? It even comes with a built in search facility for when it's deployed on a webserver.

Cheers

Munch

PS Did I mention the todo list organiser? If you put a

Code: Select all

/todo

or

Code: Select all

@todo

tag in any of your doxygen comment blocks it will automatically pick it up and add it to the todo list page, which is a great way of seeing what you've got left to do in the code - there are so many cool features to this tool!

[jcnossen]

Hmm the todo list thing sounds really useful. Nice idea.

[Fnordia]

Sure, guess I could put something like that up on the spring webserver.

[munch]

Sure, guess I could put something like that up on the spring webserver.

Cool! =) Just to warn you, if you switch all the diagrams on, you get around 0.3GB of output - is that OK? Each page is only in the kilobytes though - there are just a lot of pages!

FWIW here is an example diagram (a "collaboration diagram" for the ExtractorUnit class in fact):



This is just a one off example of one kind of diagram generated by Doxygen from the Spring source code, but in the Doxygen webpage where this lives, you can click on any of the other classes to see their diagrams and associated documentation.

Fnordia (or anybody else for that matter) if you want any support on this just ask =)

Cheers

Munch

[FireCrack]

IIRC Doxygen also supports lua, wich is fairly convinient.

[Fnordia]

Well, space is not really a problem. So feel free to post a nice configfile I can use. :)

[munch]

Hi,

I've uploaded the file to FU (I wasn't sure if there was anywhere to upload it directly to the Spring site):

http://www.fileuniverse.com/?p=showitem&ID=1624

This has all the good stuff switched on (assuming I didn't forget anything), but with compact inheritance trees, instead of UML ones - I find that full UML style inheritance diagrams can be a bit unwieldy for large classes. The compact representation just shows the class names.

To use it, copy the file to the root of the source code tree and then either do "doxygen config-compact-class-diagrams.dox" at the command line (doxygen.exe needs to be on your PATH), or on Windows, just double click the file and select "doxygen.exe" to open the file with.

The ouput should appear in the directory above the root of the source code tree, in a folder called "doxygen-html". I've switched the Search facility on, though I'm not sure how you need to configure that to get it working on a webserver - you might need to look at the doxygen manual if it doesn't work immediately. Alternatively, it's easy to switch off. Open the .dox file in any editor and go to the very end of the file, which looks like this:

Code: Select all

SEARCHENGINE           = YES

Just change the YES to NO, so that you get:

Code: Select all

SEARCHENGINE           = NO

NB The config file assumes you've got the graphviz stuff installed in the default location.

Let me know if you have any questions - I'm no expert, but I'll help if I can =)

Cheers

Munch

[FLOZi]

Sooo... Javadoc for C++

[Tim Blokdijk]

Hi,

I've uploaded the file to FU (I wasn't sure if there was anywhere to upload it directly to the Spring site):

...

Cheers

Munch

Top right of the Spring site "Submit files"?

[cain]

whhaaaaaa

**THANKS**

I've evaluated a old version of this lot of revision ago and was plain useless, but now **ROCKS**

exactly the tool that I was missing

[Fnordia]

Ok, it took a little while for it to complete but it's now online here: http://taspring.clan-sy.com/doxygen/

[Dwarden]

[Dragon45]

Sweetness!

My Apache deployment has even more use now!

*cheers*

[munch]

Ok, it took a little while for it to complete but it's now online here: http://taspring.clan-sy.com/doxygen/

Great - thanks Fnordia =) Yeah it does take a while to process that amount of source code! Worth sticking a link to it somewhere?

Top right of the Spring site "Submit files"?

D'oh! Thanks. Where do files uploaded like that end up?

Cheers guys!

Munch

[PauloMorfeo]

Ok, it took a little while for it to complete but it's now online here: http://taspring.clan-sy.com/doxygen/

That looks cool.
Now all we need is a link to it (next to the news/wiki/... links). Or is it there already and i missed it?

[jouninkomiko]

... i kept thinking how useless this would be oon the spring sources. then i used it. nice :) good idea, and good work munch

[munch]

Well I didn't really do any "work" as such, the doxygen guys already did all that! I just put the idea forward and Fnordia kindly put it on the site. Glad you like it though - I just hope it helps =)

Maybe now it's there people will start putting Doxygen style comments into their code, which makes it all the nicer. It's the same syntax as Javadoc basically. If yo'ure not familiar with that, the main thing you need to know is to use

/**

At the start of your comment blocks (it also works with /*!). Or on the otherhand if you prefer using // style comments, use /// (or //! if you prefer).

Within the comment blocks you can also use special commands - see http://www.stack.nl/~dimitri/doxygen/commands.html
for details.

I guess I should maybe add the above text to the wiki!

Cheers

Munch