On 10/7/2017 12:25 PM, Robert Ramey via Boost wrote:
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.
The major problem with library docs is always that programmers become too lazy to explain what the various things are that library actually does and what the constructs are to achieve each of those various things. Instead, for too many programmers, library documentation is 99% examples and a reference, the latter being nothing more than a listing of constructs which can be used, with no explanation of when or why one might want to use them. That's it for an awful lot of developers ! And as long as programmers in general consider that as adequate documentation, library developers will continue to follow that model. Even when you point out to programmers that such documentation is inadequate for end-users who actually want to use your library, the usual response is just bafflement that the end-user doesn't "get it". I understand that programmers do not want to write documentation, but want to create really nifty and useful libraries and programming constructs. I understand that many developers are not native English speakers and find it quite onerous to write documentation in a secondary language which they can almost never know as well as their own primary language. I sympathize with both these problems. But unless docs can explain to end-users what is useful about a library and how that usefulness translates to the constructs of that library, library documentation will not be adequate for a great many intelligent programmers. I feel like an old dinosaur writing this. The current age of computer programming expects so little of documentation that I am probably already obsolete in my documentation needs. But I hope programmers will try to understand that the most brilliant library is useless if it cannot be understood or, conversely, if understanding it takes such an inordinate amount of end-user's time that he just gives up in trying to use the library. I think very little of this has to do with tools per se. I am certainly for the best tools which anyone finds easy and adequate to use. Rather this problem has to deal with the approach to documentation as a means to explain what one offers as library functionality.
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