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

Subject: Re: [boost] [review] Review of Outcome (starts Fri-19-May)
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-05-27 01:02:59

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.

Thanks