Re: [boost] Copy editing documentation - SOC project

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-03-08 17:54:58

Matthias Schabel wrote:
>>> 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.

FYI, QuickBook already has the reverse-lit feature. It lets you
"import" code snippets from actual code. Rene and I are using it
right now to great effect.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net