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

Subject: Re: [boost] [review] Review of Outcome (starts Fri-19-May)
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-05-27 13:55:27

> 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 probably didn't tell you I tried a docca build of Outcome's docs. I
also gave a go of standardese, and doxyrest which is another doxygen XML
to Sphinx converter.

In all cases I felt that while the appearance of the documentation
improved, but I also felt that the **utility** of it dropped. Part of
that would be the additional work to fill in the missing gaps of doxygen
markup support in each of the tools above, but also because things like
keyword search don't work right, or member function documentation is too
bunched together visually, or too many really long pages get generated
which drown out detail. doxygen's output is ugly, but you can find what
you want fairly quickly.

I thus settled on doxygen as being the least worst of the alternatives
available to me. Don't get me wrong, it sucks, but it is less painful to
maintain than any of the others. One of my biggest peeves with all these
doxygen alternatives is how much pain they cause me to update the
documentation. If I have to run anything more than a single command
which does it all, I don't like it.

If Outcome is accepted, I may make an attempt at my own documentation
generator based on libstandardese for the code parsing, but generating a
https://gohugo.io/ website. I'm as sick and tired of awful documentation
as everyone here, but I also want something with **zero** maintenance
overhead for me, ideally something which goes into the cmake build cycle
and I literally never, ever have to think about it.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/