C++ library documentation: was [boost-ext] DI questions

From: Robert Ramey (ramey_at_[hidden])
Date: 2021-02-22 01:43:49

On 2/21/21 11:47 AM, Edward Diener via Boost wrote:

> Libraries need more than a tutorial. I find tutorials helpful, but if I 
> can not understand the various functionalities of a library, no amount 
> of tutorial explanation helps me. By functionality I do not mean just a 
> reference, but an actual written out explanation of the basic concepts 
> of the library, how they are embodied in classes, and how they fit 
> together, as well as a basic explanation of the pros and cons of using 
> the functionality. I gather that I am old-fashioned, but I just do not 
> want to have to do the work of figuring things out for myself through 
> tutorial examples and a reference, because inevitably I will want to do 
> things which are not explained by some example and I will be lost 
> without understanding what the various pieces of a library actually do. 
> This is not a knock against the DI library but just a general appeal for 
> explanations rather than just the examples/reference type of docs.

Edward,

You've made this points several times in the past.  I've had a lot to 
say about C++ library documentation:

a)what it should and should not contain
b)it's relationship to the header and implementation code
c)it's relationship to C++ concepts
d)structural organization
e) ... other stuff

I even gave a presentation of my views at CPPCon: 
https://www.youtube.com/watch?v=YxmdCxX9dMk

An example of faithful application of these ideas can be found by 
looking at the documentation of the safe numerics library.

I'd be curious to hear your thoughts on this work.

Robert Ramey