Re: [boost] Copy editing documentation - SOC project

From: Matthias Schabel (boost_at_[hidden])
Date: 2007-03-08 17:29:36

>> I'd be interested in hearing your views. As an aside could the class
>> documentation not be generated directly from the source using  
>> something
>> like Doxygen?
>
> I personally don't like docs produced using Doxygen (or similar).  
> They still
> require considerable effort and in most cases look like reference  
> rather
> than users guide/tutorial.

Being in the thick of documentation right now, I think it would be a  
great SOC
project to try to extend/adapt Doxygen to ameliorate these issues  
while preserving
it's nice aspects. It would also be great to extend it so that code  
snippets can be
directly inserted by name into the documentation (sort of like  
Knuth's WEB system
in reverse) so that the code and dox stay in sync (this is one of the  
todos on the
Doxygen web site already). That said, I like a lot of the aspects of  
Doxygen - better
control over sectioning and pages and extended syntax for mainpage.h  
would
be a great extension.

Matthias