Re: [boost] [log] Documentation v2 mini review

Subject: Re: [boost] [log] Documentation v2 mini review
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2013-01-19 05:29:38

On Friday 18 January 2013 13:01:41 Klaim - Joël Lamotte wrote:
> 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.

Thank you for the review. I have made the corrections according to most of 
your suggestions in the bleeding-edge. On the rest my comments follow.

> Design overview:
> ================
> 
> 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?

Loggers are still character dependent, as well as some sink backends (Windows-
specific and text_ostream_backend because the underlying API is character-
dependent). I removed the second sentence to avoid confusion.

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

I understand your concern but either graphical solution clutters the image or 
doesn't look good aesthetically. Besides, I think the rest of the docs makes 
it clear that there is no direct connection between sources and sinks. 
However, I might add the fourth output path if I come up with a good variant 
of "(something else)".

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

Well, I didn't emphasize too much attention on C++11 features because most of 
them would be used transparently for users. E.g. the library will use native 
move semantics when possible. As for C++11 lambdas, except for some corner 
cases (which are marked with notes where appropriate) they are treated as any 
other function objects, so there's nothing really special about them.