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://listarchives.boost.org/mailman/listinfo.cgi/boost
>