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:
> 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:
> "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.
> 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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk