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 personally from 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. To summarize: 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. Robert Ramey