Subject: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-05-27 16:09:59
On 5/26/17 11:57 PM, Vicente J. Botet Escriba via Boost wrote:
>>
> I believe what Robert mean is that the generated documentation of
> Boost.Outcome using doxygen has a lot of flaws.
> Of course it is tempting to say that it is because of doxygen.
>
> As you showed in the examples we can do better. Using Doxygen requires
> to be more careful and sometimes replace some possible issues by
> workaroounds.
>
> Nevertheless Doxygen on code using the pre-processor is a nightmare.
> Have you experience on these cases?
>
> I will tale a deeper look at your examples :)
>
I understand the appeal of Doxygen. The idea if annotating the code
with narrative comments which can accessed in a user friendly form is
very appealing. It's natural for a programmer, easy to do, easier to
keep up to date and is less tedious than building a giant reference
after the fact. It also embodies the ideas and principles of literate
programming in a practical way. So I see a lot of good in it.
BUT
a) It's support for templates is limited to specification of template
parameters. It has no way to specify Type Requirements (aka concepts)
aside from just typing in the narrative. It has no way to specify a
concept and refer to it.
b) It's doesn't seem a convenient method for specifing things like
tutorials, examples, design concepts etc.
c) By providing a place to add a little narative to each method it gives
the programmer the impression that he's documenting his library - which
he is not actually doing. In most cases all he is doing is making the
comments in the code visible through some browser. Nothing wrong with
this, but he's not really adding anything that one couldn't gain from
just browsing the source code.
d) If your source code isn't readable, you can create the impression
that it's designed when it fact it isn't. That is it's useful for
obscuring the fact that your code actually doesn't have any kind of design.
So, for fans of Doxygen who have nothing else to do:
a) Figure out how Doxygen customization works. I see this is huge slew
of macros and settings which .... - well I don't know what it does. I
guess it needs better documentation or perhaps design.
b) Figure out how to express a concept in Doxygen and refer to it.
c) Restrict usage of Doxygen to building xml reference pages for classes
and class templates, functions and function templates.
d) figure out how to meld this reference boost book using some other
tool like quickbook, xml_mind, emacs or whatever.
e) Be sure you make a good explanation so some naive person can create
library documentation with your tools.
e) If you get all this right - a tall order - be prepared to invest a
lot of effort to evangelize your solution. This will be a very long and
frustrating exercise.
Or if you want to strike out on your own separate path - generally my
own personal preference - you might consider an approach like caramel
which would build on the idea of embedding boost book tags in comments
and post processing the code.
That's all I have to say about that.
Robert Ramey