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

From: Edward Diener (eldiener_at_[hidden])
Date: 2021-02-22 03:51:25

On 2/21/2021 8:43 PM, Robert Ramey via Boost wrote:
> 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.

I like your Safe Numerics documentation. I am certainly not against 
Boost-ext docs, but was just reflecting that the confusion about 
understanding DI might be solved by a different documentation approach.