Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-07 16:25:24
On 10/6/17 8:12 PM, Steven Watanabe via Boost wrote:
>> If we can get it working, it'll be a whole new age of "easy" for writing
>> docs for complex C++ codebases,
> Er, I've always considered the hard part of documentation
> to be the organization and content rather than specific tools.
So, so, so, true. I huge problem these days is that the attractive
presentation of documentation gives the impression that documentation is
well done. It's very, very misleading. It's a plague. I have a lot to
say about this very phenomenon in my recent presentation at cppcon 2017.
Hopefully the video will be available shortly. I wasn't totally happy
with my presentation, testimony to how difficult is to capture the
problem and address it.
There have been a few recent boost library submissions which have
suffered in this area to the extent I believe they may have turned a
possible acceptance to a rejection. In one case I believe that a
previously rejected library was accepted and a large part of that change
of assessment was due to much improved documentation.
So, contrary to what one might think, I do believe we are making some
progress in this area.
>> and moreover one which finally can parse
>> the worst possible C++ metaprogramming without blinking because anything
>> clang can parse can be documented.
> Just because the parser can handle it, doesn't mean that
> it's a good idea. For example, in documentation, I always
> hide complex SFINAE, and instead provide an English description
> of the conditions. In general, I find the more complex the
> metaprogramming is, the more tweaking is required to turn
> the doxygen output into something sane. This is rarely because
> doxygen can't parse the code, but is rather because the raw
> definitions in the source are not very human-friendly.
The question of how to document/explain certain C++ constructs such as
template parameters, concepts and meta functions is an interesting one.
Tools like Doxygen and others don't address this. It's not obvious and
not described by any "tutorials" on documentation. Actually, there
isn't even a concensus. 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. SGI documents
describe documentation standards in detail - but this is almost ignored.
>> You can see our joint efforts so far for Outcome v2 at
>> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
>> written so far, it's all him.
Andrezej is a great writer who understands all this. I know this
a) reading his blog
b) going back and forth with him on the documentation structure of the
safe numerics library. Though this effort is better than most, there
have been a lot of problems with this and he is one of the few that
understands this stuff. We share a common view as to what documentation
should be. So his criticisms are on point and almost always correct.
He is also very meticulous which helps me a lot.
a) Our (boost and C++ generally) problem is not rooted in the tools,
though the tools don't help much.
b) There is growing recognition that it's a serious problem both in
boost and C++ generally.
c) In reviews, we're more critical of documentation than we used to be
and suggestions to improve it are more constructive.
So things are slowly getting better. I'm optimistic about the future.