[boost] [Logging] Documentation comments.

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

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

   * http://torjo.com/log2/doc/html/scoped_logs.html
     * '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'.

   * 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'.
     * '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 
initialized'.
     * Inconsistent final paragraph and example order in 
BOOST_LOG_BEFORE_INIT_LOG_ALL and BOOST_LOG_BEFORE_INIT_CACHE_FILTER 
documentation.
     * 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?

   * 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?

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

   * 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?

   * 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?

   * 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.
     * '(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ć