Re: [boost] Asciidoc, an alternative for documentation

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.

Niall

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