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

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 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.ht...

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_str...

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