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