[boost] [log] review part 1

Subject: [boost] [log] review part 1
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2010-03-11 23:22:10

AMDG

I mostly have documentation notes at this point.  Andrey, since I have so
many, and they're mostly fairly minor, would it be better if I made
a patch for the documentation source?

I think newbies should probably be replace globally with new users,
since I kind of feel that the term newbie is somewhat derogatory.

http://boost-log.sourceforge.net/libs/log/doc/html/log/moti.html:
================================================================================

Mismatched number:
Most of the time ***applications*** ... to monitor ***its*** execution...

The beginning of the second paragraph could be improved:
"This is where logging may help. The application stores all essential
information of its run time to log, and once something goes wrong this
information can be used to analyze program behavior and make necessary
corrections."
Here's my suggestion:
"This is where logging can help. The application stores all the essential
information about its execution to a log, and when something goes wrong this
information can be used to analyze the program's behavior and make the
necessary corrections."

"out-of-box" should be "out-of-the-box"

This phrase sounds rather clunky to me:
"...along with public interfaces ready to be used to extend the library."

This too:
"A user should be able to extend functionality of the library with regard
to collecting and storing information into logs."

"The library should make as least performance impact..." should be
"The library should have as little performance impact..."

http://boost-log.sourceforge.net/libs/log/doc/html/log/how_to_read.html:
================================================================================

In the beginning of the second paragraph, I don't like the phrase
"to have the first glance on" How about something like "...to get
a feel for the library's capabilities..."

"The tutorial gives the overview of the library features..."
Suggestion:
"The tutorial gives an overview of the library's features..."

"The simple form typically describes the most common and easy way to do
the task and it is being recommended to be read by newbies."
Suggestion:
"The simple form typically describes the most common and easy way to do
the task and is recommended for new users."

"The advanced form usually gives an expanded way to do the same thing but
with ability to do some extra customization and in-depth explanation."
I would like a definite article before "ability" and I would also
like "and in-depth explanation" to be placed differently so that it
doesn't sound like you're saying that the user has the ability to do
in-depth explanation.

"This form may come handy for more experienced users and should generally
be read if your needs are not satisfied with the easy way."
Suggestion:
"This form may come in handy for more experienced users and should generally
be read if the easy way does not satisfy your needs."

"This part gives description of other tools..."
should be
"This part gives descriptions of other tools..."

"This chapter is better to be read on per-case basis."
Suggestion:
"This chapter is best read on a case by case basis."

"there is a reference which gives the formal description of
library components. "
The work "description" should be plural, "descriptions".

"For simplicity in the code snippets in this documentation it shall be
assumed that the following namespace aliases were defined"
Suggestion:
"To keep the code snippets in this documentation simple, the
following namespace aliases are assumed to be defined"

"Aside from these namespaces the library also provides
boost::log::experimental namespace."
Suggestion:
"In addition to these namespaces the library also provides
the boost::log::experimental namespace."

"and thus are not advertized for productional usage"
The word "productional" should be "production"

http://boost-log.sourceforge.net/libs/log/doc/html/log/supported_compilers.html:
================================================================================

"The library should build and work with a reasonably well-compliant 
compiler"
delete "well-"

http://boost-log.sourceforge.net/libs/log/doc/html/log/installation.html
================================================================================

"The library has the compiled part which should be built as described
in the Getting Started article."
Suggestion:
"The library has a separately compiled part which should be built as 
described
in the Getting Started guide."

For BOOST_LOG_NO_THREADS
"Has effect on both the library compilation and user's code compilation."
Suggestion:
"Affects compilation of both the library and users' code."

"The macro is automatically defined if no threading support detected."
add "is" before "detected"

For: BOOST_LOG_USE_CHAR
Same as the first comment for BOOST_LOG_NO_THREADS. (This appear
many times, I won't repeat it again)

For: BOOST_LOG_USE_WCHAR_T
"it is assumed the both character types support is enabled"
Suggestion:
"support for both character types will be enabled"

"Defining only one of them allows to significantly reduce
binary size of the library."
Suggestion:
"Defining only one of them significantly reduces the
binary size of the library."

For BOOST_LOG_NO_QUERY_PERFORMANCE_COUNTER:
"If defined, disables support for QueryPerformanceCounter API"
Suggestion:
"If defined, disables support for the QueryPerformanceCounter API"

For BOOST_LOG_USE_NATIVE_SYSLOG:
"Has effect on the library compilation stage."
Suggestion:
"Affects only the compilation of the library." (repeated later as well)

"If for some reason the support for native SysLog API is not
detected, define this macro to forcibly enable support for native SysLog."
Suggestion:
"If for some reason support for the native SysLog API is not
detected automatically, define this macro to forcibly enable it."

For BOOST_LOG_NO_SETTINGS_PARSERS_SUPPORT:
"If defined, all facilities related to settings parsing are not built."
Suggestion:
"If defined, none of the facilities related to the parsers for settings
will be built."

"You may define configuration macros..."
should be
"You can define configuration macros..."

http://boost-log.sourceforge.net/libs/log/doc/html/log/defs.html
================================================================================

For Log record:
I don't like the expression "A single pack of information," although
I can't think of anything better off hand.

"that is candidate to be put into log"
Suggestion:
"that is a candidate to be put into the log"

For Attribute
"functional objects" should be "function objects"

"which return the actual attribute value upon invoking"
Suggestion:
"which return the actual attribute value when invoked"

For Log sink:
"collected from user's application"
should be
"collected from the user's application"

"It is sink's nature that defines where..."
Suggestion:
"The sink defines where..."

For Log source
"An entry point for user's application..."
should be
"An entry point for the user's application..."

"upon user's request" should be "upon the user's request"

For Log formatter
"functional object" should be "function object"

"...that forms up the final shape of the textual output"
is awkward.

"Some sinks, like binary logging sink"
should be
"Some sinks, like the binary logging sink"

For Logging core
"The global entity that maintains connection between"
should be
"The global entity that maintains the connection between"

"It is mainly used on the logging library initialization stage."
replace "on" with "in."

http://boost-log.sourceforge.net/libs/log/doc/html/log/design.html
================================================================================

I htink "scheme" with "figure"

"The library provides configuration facilities to leave only one needed
version of the library to be compiled."
Suggestion:
"The library provides configuration facilities to compile only the
version of the library needed."

"For example, if your application is in critical state"
should be
"For example, if your application is in a critical state"

"so that user sees an error message..."
should be
"so that the user sees an error message..."

"This allows to use the library"
Suggestion:
"This allows use of the library"

"...require users to use loggers to write logs"
"use" and "log" are used too many times here.

"The more generic term "log source" is used to designate the entity"
Suggestion:
"The more generic term "log source" designates the entity"

"You may see on the scheme that the"
suggestion:
"You can see on the scheme that the"

"and allows to quickly wipe away unneeded log records"
suggestion:
"and allows quickly wiping away unneeded log records"
anyway, don't split infinitives.

"The sink-specific filtering allows to direct log records to particular 
sinks."
Suggestion:
"The sink-specific filtering allows log records to be directed to particular
sinks."

"Backends, on the opposite"
suggestion:
"Backends, on the other hand"

"most probable places of the library extension"
suggestion
"most likely places for extending the library"

"Along with the described above primary facilities"
should be
"Along with the primary facilities described above"

================================================================================

Issues:

Instead of compiling a narrow or wide library, why don't you use 
libboost_log
and libboost_wlog?

I agree with other comments that I saw about Attribute being
a poor choice for what it does.  I would prefer that the term "Attribute"
should be used for what you call an "Attribute Value," and that
there should be a different term, like "Attribute Extractor" for
what you call an "Attribute."

In Christ,
Steven Watanabe