Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-16 05:32:34

On 8/15/17 5:09 PM, Edward Diener via Boost wrote:
> On 8/15/2017 4:18 PM, Robert Ramey via Boost wrote:
>> On 8/15/17 12:54 PM, Edward Diener via Boost wrote:

> Are you aware that you can do free form documentation with doxygen as 
> long as you use one of there many general syntaxes for starting/ending 
> in-line documentation ? So obviously you can a) or b) with it. There is 
> absolutely no reason to be constrained solely with using one of their 
> keywords for everything you want to document.

I don't remember the details.  But I did spend some time looking into 
it. I came away thinking it would be too much work/development to give 
it what I think it needed to be effective for something like boost 
libraries.

I was willing to accept a certain amount of comment cluttering as I do 
appreciate the appeal of literate programming.  I also looked into 
caramel and other xml based systems.  I spent significant amount of time 
on this.

But my conclusion is/was that the code and documentation are not quite 
close enough to make this work.  That is, documentation create this way 
often doesn't add a heck of lot which isn't already in the code itself. 
This system I'm going to promote actually creates shorter documention 
than that produced by doxygen and it has stuff that the typical doxygen 
documentation doesn't.  To put it another way, that while documentation 
and code are closely related, I don't think there's a one to one mapping 
between the two.  So I see good looking docs being produced which are 
not as helpful as I think they could be.

Robert Ramey

> 
> 
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost
>