Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-16 00:09:02

On 8/15/2017 4:18 PM, Robert Ramey via Boost wrote:
> 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.

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.

> 
> 
>>> Robert Ramey