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