Boost logo

Boost :

From: Jurko Gospodnetić (jurko.gospodnetic_at_[hidden])
Date: 2008-02-10 00:27:14

   Hi John.

   Just some more notes I took while reading the documentation. Some are
corrections and some are questions.

   * Change-log has some old revision notes (0.4 - 0.7) ordered incorrectly.

   * Term 'namespace' as you use it when not referring to C++ namespaces
should most likely be changed to 'concept', but I believe someone
mentioned this.

   * Some nitpicking.
     * Many lists inconsistently have items with and some without a
trailing dot.
     * Many lists inconsistently have lowercase/uppercase leading letters.

   * Feature list at
     * Lose the 'as you'll see' at the end of the thread-safety feature.
Such extra commenting is OK for some 'monologue' part of the
documentation like some rationale explanation but does not seem to fit here.

   * Generally do not write the docs using first-person style. That way
the docs become too personal and may irritate the reader because he
takes the information in it too personally. Again... may be OK for some
parts but for most of it phrases like 'I do not know...' should be
replaced with 'There is no way to know...' or something similar.
     * Example: 'Note that I encountered a very big problem, when
implementing scoped logs: I don't know how you gather your message, when
using the logs. In other words, I don't know your Usage Syntax. So I had
to make a few assumptions, as you'll see.'.

     * 'as first' ==> 'as the first'.
     * Phrase 'You cannot use any variable from your scope, nor any
other variables' when describing BOOST_SCOPED_LOG seems unclear. Most
likely remove it as its point is actually implied by the first item on
that same list.
     * 'contactenates' ==> 'concatenates'.
     * '...are allowed' ==> 'Multiple scoped logs are allowed'.

     * 'which, until you initialize your logs, do some logging' ==>
'which do some logging before you initialize your logs'.
     * 'and it its body' ==> 'and in its body'.
     * 'context do rely on' ==> 'context do rely on'.
     * mark_as_initialized() function.
       * Could use a link from here to the appropriate reference manual
part of the documentation.
       * If the user does not call this function explicitly, when will
it get called? And why do you keep calling it explicitly in all the
example code?
       * Seems like a bad name for what it is intended to do. If it
actually does change the logger's state to 'initialized' then it should
be an internal implementation detail function and not made public. If it
only raises a flag meaning 'do not cache log messages for this logger'
then it should be renamed to something like disable_caching() or
enable_caching( false ).
       * Documentation here gets a little mixed up with what you are
supposed to call this function on: the log or the cache. Also it is not
clear what is supposed to be considered initialized.
         * E.g. 'when cache is marked as initialized' is not something I
can understand intuitively... how can a 'cache' be initialized... what
could this 'cache initialization' be since log messages have already
been cached and later on there is no need for this 'cache'.
         * In another place you state 'when the log is marked as
     * Inconsistent final paragraph and example order in
BOOST_LOG_BEFORE_INIT_LOG_ALL is on by default do the other two simply
override this one? Or is the user expected to disable this one somehow?

   * Update copyright notices to 2008.

   * Common Usage paragraph has a line saying 'Click to see the code'
which is not a link to anything. :-) The same example is duplicated as
Scenario 1 and there this line is linked correctly. Is this your doc
tool bug or is there actual content duplication here?

     * States scoped logging will be implemented soon, while it already
has been.
     * 'statemets' ==> 'statements'.
     * 'Thoghths' ==> 'Thoughts'.

   * How would one achieve the following: you have an application
logging messages organized into different groups
(categories/whatever...) and you want to say at run-time: log this group
to this file and to debug output, do not log that group at all and log
that third group only to this file. Would this require separate logger
objects? Or can filters somehow decide which destinations they

   * What are the exception safety guarantees? What can throw
std::bad_alloc for example? What other exceptions can be thrown by the
Boost Log library? If ordinary logging can throw, is it safe to use in
destructors and how can scoped logging be safe then at all?

     * What is that '#include <boost/logging/format_fwd.hpp>' line in
the 'Tags - explained' part.
     * '(from optimize namespace)' should be linked to the corresponding
namespace/concept reference documentation.

   And now it's 6:19 here... and I really need to get some sleep too.
:-) Will try to finish reading the docs tomorrow but will not be able to
try it out and prepare a review until later next week.

   Hope this helps.

   Best regards,
     Jurko Gospodnetić

Boost list run by bdawes at, gregod at, cpdaniel at, john at