Re: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)

Subject: Re: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-12-13 09:08:40

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Artyom
> Sent: Monday, December 13, 2010 1:22 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] [Documentation] Does Boost-Build support Doxygen
> documentation for tutorials (rather then quickbook)
> 
> >
> > Downside :-((  the  results are not as nice  ;-)
> 
> The results is the content not the "nice representation" and to be honest,
> Doxygen reference documentation is a way better then the "reference"
> I usually see in boost libraries.

I'm curious in what way you think it is superior.

And of course, you can *also* view it in Doxygen format, if you prefer,
provided the Doxygen files are provided in the download.

I've been arguing for some time that this should always be provided.

I also feel that much of the benefit from Doxygen comes from the 'in-code'
documentation of each function.

This also feeds through into the Quickbook reference section.

But it needs Doxygen documenting while writing the C++ code, as you go
along.

I found that adding it later was very tedious (and I'd forgotten what some
things were meant to do! ;-)

If I were starting a new project, I would definitely do this - then I might
be able to understand my own code a year or so later ;-)

I have found it best to run Doxygen (which is quick and gives better error
messages for Doxygen comments mistakes) to check before running the full
Quickbook html and pdf output.  Build time is significant if you have a good
sized package (Boost.Math and SVG Plot are both over 500 pages in pdf) -
though it has improved markedly with Steven Watanbe's recent good work - for
which many thanks (and with a little help from some faster hardware ;-)

I still urge you to get the whole Quickbook thing to work - however painful
it may seem.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]