Boost logo

Boost :

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

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:

Boost list run by bdawes at, gregod at, cpdaniel at, john at