Re: [boost] [log] how to set attributes under multi-threaded application

Subject: Re: [boost] [log] how to set attributes under multi-threaded application
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2011-08-04 14:20:09

On 08/04/2011 09:13 PM, Sean Chittenden wrote:

> This is a general comment about the documentation across the boost
> project and isn't entirely specific to the boost-log project, but
> wisdom such as this "the application of XYZ feature is ideally suited
> for the situation ABC" doesn't exist frequently in much of the boost
> documentation. I don't know if it's in some style guideline
> someplace, but having been a boost user for ~5yrs now and having
> forced boost on other developers for a few years now, this is one of
> the things that I acutely notice/get push back on regarding the boost
> project (especially when referencing its documentation).

[snip]

> Anyway, Andrey, it'd be keen if you could include a note along these
> lines in the docs. Maybe a quickbook type for "Implementors."

Well, although I admit that new users of Boost and Boost.Log in 
particular may be missing this kind of case-by-case style docs, this 
approach is just not practical. Boost libraries are known for their 
flexibility, even the author doesn't always know in what ways his 
library is going to be used. Describing each case in the docs will take 
ages, the resulting docs will be too large to comprehend and there will 
still be lots of users with their cases not being covered. I think the 
common formula "library design + tutorial + features description + 
reference" is the golden middle for medium-sized projects, like 
Boost.Log. Also, quite a few common case examples will help to get 
things started. The rest will come with experience.

As a side note, this kind of scenario-based description or "words of 
wisdom" is probably better suited for books and articles rather than 
library docs. I'm not saying it's useless (just the opposite, actually), 
it's just not what I usually seek in the library docs.