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