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.