[boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)

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