Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-10-07 21:55:32
> In a recent review, I complained that
> requirements on template parameters weren't document.Â The library
> submitter countered that it wasn't necessary because the code contained
> static_asserts to enforce (otherwise undocumented) requirements.Â Even
> the C++ standard calls for this - yet it's often skipped.
Luckily for you Concepts (and C++ 20? I am unsure) brings the "requires"
keyword, thus ensuring that every single template can simultaneously
document and constrain its types in straight C++.
No documentation tool, including Standardese, is currently able to
extract requires clauses yet though. But it'll come eventually.
(And yes, Outcome v2 is 100% Concepts TS ready, and thus all templates
and their parameters specify their requirements)
> Andrezej is a great writer who understands all this.Â I know this
> personally from
He's doing a great job with Outcome. So much so I intend to leave him at
it. I'll write my usual word soup for the advanced tutorial sections
such as how to use the ADL customisation points etc. But I am not
capable of better in the time I have available to me.
> a) Our (boost and C++ generally) problem is not rooted in the tools,
> though the tools don't help much.
Boost tooling is painful. I have to think with Boost tooling. I don't
want to have to think, I want to get on with it.
doxygen suffers badly from this too as soon as you push it a bit. You
end up writing lots of simplifying constructs for it with #ifdef.
Painful. Standardese doesn't suffer from that part at least.
-- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk