[boost] [outcome v2] Pre-review feedback

Subject: [boost] [outcome v2] Pre-review feedback
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2018-01-05 23:33:20

Outcome v2's review starts on Friday 19th January, after which I can't
fix even obvious problems. The documentation is by far the newest and
most experimental part using bleeding edge tooling, so getting a few
rounds of fixes in now before locking everything down for the review
would be great.

Can those who are super keen have a look at the reference API docs and
find problems that me and Jonathan can fix before the review begins? You
can find the reference API docs at:

https://ned14.github.io/outcome/reference/

And issues can be logged to https://github.com/ned14/outcome/issues
or https://github.com/foonathan/standardese/issues if you're sure of the
source of the problem.

Potential problems to look out for (not a complete list):

- Lack of documentation summary string
- Confusing or meaningless documentation
- Incomplete or mangled documentation for some entity (e.g. sentences
missing sections, lines reordered)
- Leakage of "detail" namespace or of types or macros clearly of
internal implementation detail
- Stray or missing commas, angle brackets, brackets
- Missing or insufficient requirements, effects or throws clauses
- Appearance of any `std::enable_if`, these are supposed to be
suppressed into requirements, but I know `outcome.hpp` is particularly
bad on that (tracked by https://github.com/ned14/outcome/issues/76).
- Lack of hyperlinking to other parts of the reference docs where that
was clearly intended.

To expand on the "bleeding edge tooling" part, these reference API docs
are generated using https://github.com/foonathan/standardese which is
based on clang libtooling. Some of the problems are caused by clang
libtooling, some by standardese, some by me. I don't doubt that these
reference API docs are an enormous improvement over those from doxygen -
especially the ability to search semantically for stuff related to
search term - but there are a lot of very small problems I'd love to
clean up before the formal review begins.

Thanks in advance.

Niall

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