[boost] [log] Documentation v2 mini review

Subject: [boost] [log] Documentation v2 mini review
From: Klaim - Joël Lamotte (mjklaim_at_[hidden])
Date: 2013-01-18 07:01:41

Hi,
I took some time to read the new Boost.Log documentation, at leas the
beginning and the parts that interest me the most.

First, it is very complete and clear, so this is good.
I didn't try the code yet but will report about it in coming weeks (I guess
it's ok as no mini-review date have been set yet so I'll not be late).

Here are some remarks, which are all minor improvements.

Design overview:
================

1.

"The library was designed to be very modular and extensible."

Maybe starting with "this library" or "Boost.Log" instead of "the library"
would be clearer.

Next: "The logging library " - remove this repetition.

2.

"Both narrow and wide-character loggers provide similar capabilities,
so through most of the documentation only the narrow-character interface
will be described.
The library provides configuration facilities to compile only the version
of the library that's needed."

So the recent changes you did concerning wide/narrow characters don't affect
this part of the documentation?

3.
The picture is good.

A minor improvement: it would have been better if
there was a clear sense that sources and sinks are unrelated.
One possibility would be to have crossing arrows in the logging core
to express the possibility of having custom source routed to
alarms for example.
It's a minor improvement anyway, I just fear that
visual alignement suggest a direct relationship between sinks and sources.
A simpler possibility would be to make the sinks smaller and
unaligned from the sources, like this:

                      +-----------+
embedded loggers   => |           |
                      |           | => logs
                      |           |
                      |  Logging  | => (something else)
global loggers     => |           |
                      |   core    | => alarms
                      |           |
                      |           | => statistics
custom log sources => |           |
                      +-----------+

Formatting might be wrong in your email interface so here is the same with
right formatting: http://pastebin.com/itPRd66k

Which I think would make clear that both concept are not directly linked.

4.
" - from parts of your application at the left to the final storage, if
any, at the right"
It seems that there is a missing coma?
Maybe:
" - from parts of your application, at the left, to the final storage, (if
any) at the right"

5.
In this document (and other pages), you are often listing different kind of
things. I think it might
be even clearer or fast to read if you used bullet points when you are
listing
possible variants. For example, attribute sets kinds could have each their
bullet.

To be clear: the current doc is fine as it is now, it's only a potential
improvement remark.

Trivial logging with filters
============================

6.
"The filter is built as a lambda expression."

Maybe a remark related to C++11 lambda might be important here (or before)?
To explain the difference with what you're doing in the example.
Because it's not obvious here that you're utilizing another library
to accept another style of lambda.

In general, a note about supporting or not C++11 might be helpful as this
library will be new to boost distribution users.

Hope it helps.

Joel Lamotte