On Fri, May 26, 2017 at 5:22 PM, Robert Ramey via Boost
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. Thanks