From: John Torjo (john.groups_at_[hidden])
Date: 2008-02-10 21:08:40
Jurko Gospodnetić wrote:
> 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.
>
>
done
> * 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.
>
>
I changed the wording.
> * Some nitpicking.
> * Many lists inconsistently have items with and some without a
> trailing dot.
> * Many lists inconsistently have lowercase/uppercase leading letters.
>
>
this took a while to fix...
> * Feature list at http://torjo.com/log2/doc/html/main_intro.html.
> * 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.
>
>
done
> * 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.
>
done
> * http://torjo.com/log2/doc/html/scoped_logs.html
> * 'as first' ==> 'as the first'.
>
done
> * 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.
>
I actually said it, but I wanted to make it clear
> * 'contactenates' ==> 'concatenates'.
>
done
> * '...are allowed' ==> 'Multiple scoped logs are allowed'.
>
>
done
> * http://torjo.com/log2/doc/html/caching.html
> * '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'.
>
done
> * 'context do rely on' ==> 'context do rely on'.
>
oh yes "to" rely on :)
> * mark_as_initialized() function.
> * Could use a link from here to the appropriate reference manual
>
done
> 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?
>
it needs to always be called explicitly
> * 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 ).
>
It actually gets all messages that were cached, and writes them to their
logger destinations.
> * 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.
>
fixed.
> * 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'.
>
fixed.
> * In another place you state 'when the log is marked as
> initialized'.
>
fixed
> * Inconsistent final paragraph and example order in
> BOOST_LOG_BEFORE_INIT_LOG_ALL and BOOST_LOG_BEFORE_INIT_CACHE_FILTER
> documentation.
>
fixed
> * How do BOOST_LOG_BEFORE_INIT_LOG_ALL,
> BOOST_LOG_BEFORE_INIT_CACHE_FILTER and
> BOOST_LOG_BEFORE_INIT_IGNORE_BEFORE_INIT macros work together? Since
> 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?
>
>
The other two can override it.
> * Update copyright notices to 2008.
>
>
fixed
> * 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?
>
I renamed a few scenarios and forgot to update the docs.
fixed
> * http://torjo.com/log2/doc/html/boost_logging_requirements.html
> * States scoped logging will be implemented soon, while it already
> has been.
> * 'statemets' ==> 'statements'.
> * 'Thoghths' ==> 'Thoughts'.
>
>
done
> * 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
> disable/enable?
>
>
You'd need a different logger per category.
> * What are the exception safety guarantees? What can throw
> std::bad_alloc for example? What other exceptions can be thrown by the
>
There are a few objects that can throw std::bad_alloc - the classes that
use TSS and array::shared_ptr_holder.
I can pre-allocate some memory for the shared_ptr_holder and it will be
a bit harder for the TSS classes.
> 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?
>
>
I can use std::uncaught_exception in the scoped logger's destructor.
> * http://torjo.com/log2/doc/html/namespaceboost_1_1logging_1_1tag.html
> * What is that '#include <boost/logging/format_fwd.hpp>' line in
> the 'Tags - explained' part.
>
what you need to include in order to use tags
> * '(from optimize namespace)' should be linked to the corresponding
> namespace/concept reference documentation.
>
>
done.
Thanks for the feedback!
Note: I'll upload the changes to http://torjo.com/log2/doc/v3/html/
Best,
John
-- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right