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.