Boost logo

Boost :

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:
> 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.

Boost list run by bdawes at, gregod at, cpdaniel at, john at