Re: [boost] [Logging] Documentation comments.

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