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

Subject: Re: [boost] [review] Review of Outcome (starts Fri-19-May)
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2017-05-27 06:57:57

Le 27/05/2017 à 03:02, Vinnie Falco via Boost a écrit :
> On Fri, May 26, 2017 at 5:22 PM, Robert Ramey via Boost
> <boost_at_[hidden]> wrote:
>> The documentation is built with Doxygen - which, though convenient, works
>> against producing helpful readable documentation.
> I must object. Both Beast and NuDB use doxygen in their toolchain, and
> I think these pages are perfectly helpful and readable:
>
> http://vinniefalco.github.io/beast/beast/ref/websocket__stream/async_read.html
>
> http://vinniefalco.github.io/nudb/nudb/ref/basic_store/fetch.html
>
> If these pages look familiar, its because they use the same doxygen,
> xslt, and boost.book toolchain that Boost.Asio uses:
>
> http://www.boost.org/doc/libs/1_64_0/doc/html/boost_asio/reference/basic_stream_socket/async_read_some.html
>
> So don't blame the tool, but blame the configuration. Doxygen
> generated HTML is terrible but with a decent XSLT program you can turn
> that worm into a butterfly. In fact, I have written such a library
> that can be included in anyone's C++ project to produce documentation
> that resembles that of Boost.Asio and Beast. Its called docca:
>
> https://github.com/vinniefalco/docca
>
> With some effort, Outcome could integrate docca and get documentation
> similar to the examples I provided above. I tried such an integration
> but I was stymied by the need to run a python preprocessor over the
> Outcome source code in order to produce valid C++ which Outcome
> requires, so I gave up. I am sure that the Outcome author could
> perform an integration since he is much more knowledgeable about his
> own code base - I am available to offer assistance with the docca
> portion.
>
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 :)

Vicente