Re: [boost] Copy editing documentation

From: Hervé Brönnimann (hervebronnimann_at_[hidden])
Date: 2007-03-12 21:58:33

I've used doxygen with great results a la doc book.  There is a  
section at the beginning of each file , @file, where you can put the  
usage examples, general documentation, rationales, etc.  Most people  
think of doxygen as only the tags after each function...  With a bit  
of patch and perl processing, it's used at Bloomberg to generate all  
the documentation, and it works great (when the documentation is well- 
written).  There can be a few glitches, but the doc always reflects  
the actual code, and it makes editing the doc so much easier.   
However when it is unfinished, it is not pretty.  That is perhaps the  
greatest disadvantage.
--
Hervé Brönnimann
hervebronnimann_at_[hidden]
On Mar 9, 2007, at 4:29 AM, Paul A Bristow wrote:
>> -----Original Message-----
>> From: boost-bounces_at_[hidden]
>> [mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy Rozental
>> Sent: 08 March 2007 20:15
>> To: boost_at_[hidden]
>> Subject: Re: [boost] Copy editing documentation
>>
>> "Nava Whiteford" <nwhiteford_at_[hidden]> wrote in message
>> news:Pine.LNX.4.44.0703081732010.24682-100000_at_vual.tchpc.tcd.ie...
>>
>>> 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.
>
> Strongly agree - OK for reference but using Doxygen usually deludes  
> the programmer that he has done all he needs to - so there is no
> "How to /How do I ..." content.  Most people 'get it' much for  
> quickly from examples - and only occasionally need reference info.
>
> Paul
>
> ---
> Paul A Bristow
> Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
> [phone] & SMS, Mobile [phone] & SMS
> pbristow_at_[hidden]
>
>
>
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/ 
> listinfo.cgi/boost