Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-15 20:18:32

On 8/15/17 12:54 PM, Edward Diener via Boost wrote:
> On 8/15/2017 1:51 PM, Robert Ramey via Boost wrote:
>
> 
> What ! Robert Ramey admitting that quickbook is not evil ? Thanks 
> Robert, for at least investigating this and deciding that quickbook is 
> usable, even if it is not your preferred choice. Maybe you can do the 
> same with doxygen <g>. Whatever your objections it is eminently usable 
> also, even while it is not perfect.

LOL - nothing's perfect.  quickbook is improvable.  On the otherhand 
there is often a temptation to improve something to try to make it do 
something that is so far beyond the original intent that you end up 
ruining it.  I know this first hand as I've done it myself many times. 
And I believe that there are better free tools for doing this.

My beef with DOxygen goes much, much deeper.  I'm aware of the idea that 
it is an implementation of literate programming and I'm credited it in 
the past for this reason.  But there are at least two big problems with it.

a) It doesn't have a good way to specify and refer to type requirements 
(aka concepts).  I think that these are more important to building a C++ 
program than most people do and Doxygen doesn't really support this. 
The most it has is TPARAM which is not enough.

b) It doesn't provide a good place/way for including program narative, 
examples, etc. This would not be a big deal as one could use it to 
generate the xml which could be transformed into a decent looking 
reference.  But the major problem is that programmers believe that this 
serves the function of documentation and DOxygen supports what I believe 
is a misconception.  When people are doing things wrong but think they 
are doing it right, that keeps us from moving forward.

I'm aware that all this  is quite a mouthful and not convincing to most 
programmers.  That's why I'm giving a presentation at CPPcon on the 
subject and my views on it.  Turns out that it has been so over 
subscribed that We're going to charge $10 to attend. So if you're 
interested, sign up asap.

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