[Discuss] doxygen

[me at mattgillen.net (Matthew Gillen)]

On 07/05/2011 09:27 PM, Stephen Adler wrote:
> Guys,
> 
> I want to use an automated web'izing documentation tool like doxygen for 
> a software project I'm working on. I'm wondering what's the use case for 
> this is. What I mean by use case is the way one adds the html generation 
> into the software development cycle. This question may be too simplistic 
> but maybe there are some general rules which would make life easy for me 
> that I wouldn't think of when I start using a tool like doxygen. For 
> example, does one only generate html documentation output when one 
> prepares the code for a release or version tag? Does one include a 
> documentation target in the make file so one can type 'make 
> documentation' How often do you generate the documentation? After each 
> make? etc. etc. If there is a web resource I should read through, I'd 
> greatly appreciate the url and any comments you guys may have.

Typically what is done in my projects is that our make system has a
'doc' target that runs doxygen.  If we have an autobuild, we will go
ahead and include the documentation in that and have the results hosted
in an accessible location (intranet web server).  Don't include the
'doc' target in the default build, since most developers won't need a
local copy; the nightly version of the API docs from the autobuild are
always sufficient.

The doc target helps with devs being able to test their in-line
documentation, and if you've got developers outside a firewall or are
otherwise difficult w.r.t. the intranet server.

HTH,
Matt