Re: [boost] Doc edits

From: Steven Watanabe (steven_at_[hidden])
Date: 2007-08-13 15:27:15

index.html:

"That it."
should be
"That's it."

tutorial.html:

"Had C++ variadic macros introduced in C99, arguments could have been passed
more traditionally BOOST_SCOPE_EXIT(commit, m_persons). Passing
Boost.Preprocessor sequence makes possible to bypass this C++ limitation."
Should be
"If C++ had variadic macros, introduced in C99, arguments could have been
passed more traditionally--BOOST_SCOPE_EXIT(commit, m_persons). Passing a
Boost.Preprocessor sequence bypasses this C++ limitation."

"A body of a ScopeExit block is executed at the end of scope of the block."
Should be
"The body of a ScopeExit block is executed at the end of scope of the block."

"In case of normal execution flow, the commit is true and code
inside the block does nothing."
Should be
"In case of normal execution flow, commit is true and the code
inside the block does nothing."

"The m_persons is also passed and it should be registered too."
Should be
"m_persons is also passed and should be registered too."

"If the first step m_persons.push_back(person) throws, the m_persons
object doesn't change and the addPerson function has no effect at all.
Note that the person  object cannot be added to an arbitrary position because
in failure case the object should be erased from a middle of the m_persons
but if copying of any Person  object after the object being erased throws,
the m_persons  is left in inconsistent state."
Should be
"If the first step, m_persons.push_back(person), throws, the m_persons
object doesn't change and the addPerson function has no effect at all.
Note that the person object cannot be added to an arbitrary position because
in case of failure the object should be erased from the middle of m_persons,
but if copying of any Person object after the object being erased throws,
m_persons is left in inconsistent state."

"BOOST_SCOPE_EXIT macro never catches exceptions. If it did, you could end up
with inconsistent state because some block couldn't execute completely. Though,
catching exceptions may be useful in some cases. The library provides a pair of
macros BOOST_SCOPE_EXIT_TRY  and BOOST_SCOPE_EXIT_CATCH_ALL."
Should be
"The BOOST_SCOPE_EXIT macro never catches exceptions. If it did, you could end
up with inconsistent state because some blocks couldn't execute completely.
Catching exceptions, however, may be useful in some cases. The library provides
a pair of macros BOOST_SCOPE_EXIT_TRY  and BOOST_SCOPE_EXIT_CATCH_ALL."

Also, I think a more important reason for not catching exceptions is that
the block ought not to do anything that could throw in the first place.
If I need to put a catch() in I want it to be explicit.  That way if
I accidentally throw I will get an obvious error rather than a silent
failure that may not manifest itself until a lot later when tracing its
cause is much more difficult.

"Below is a complete body of the addPerson. It's quite big yet easy to read.
It consists of four steps, each starts with an action followed by a rollback
action inside ScopeExit  body. Bodies are executed in reverse order.
The final step is commit."
Should be
"Below is the complete body of addPerson. It's quite big yet easy to read.
It consists of four steps. Each starts with an action followed by a rollback
action inside the ScopeExit body. Bodies are executed in reverse order.
The final step is commit."

alternatives.html:

"An instance of File  doesn't close a file in a destructor, a programmer is
expected to call the close member function explicitly."
Should be
"An instance of File  doesn't close a file in a destructor. A programmer is
expected to call the close member function explicitly."

"Though, RAII  is good for short transactions like this one:"
Should be
"RAII, however, is good for short transactions like this one:"

    * lambda expressions are hard to write correctly, for example, overloaded
      function must be explicitly casted, as demonstrated in this example,
    * forgetting to pass commit by reference may lead to a subtle bug,
    * condition in if_ expression refers to commit variable indirectly through
      _1 placeholder,
    * setting breakpoint inside if_[ ... ] requires in-depth knowledge of
      Boost.Lambda and debugging techniques.
Should be
    * lambda expressions are hard to write correctly. For example, an overloaded
      function must be explicitly casted, as demonstrated in this example
    * forgetting to pass commit by reference may lead to a subtle bug.
    * the condition in the if_ expression refers to the commit variable
      indirectly through the _1 placeholder.
    * setting a breakpoint inside if_[ ... ] requires in-depth knowledge of
      Boost.Lambda and debugging techniques.

reference.html

"Each identifier in scope-exit-args-pp-seq  must be a valid name
in enclosing scope."
Should be
"Each identifier in scope-exit-args-pp-seq  must be a valid name
in the enclosing scope."

"The ScopeExit uses Boost.Typeof  to determine types of
scope-exit-args-pp-seq elements."
Should be
"ScopeExit uses Boost.Typeof to determine the types of
scope-exit-args-pp-seq elements."

"Although BOOST_SCOPE_EXIT_TPL has the same suffix as the BOOST_TYPEOF_TPL,
it doesn't follow a convention of the Boost.Typeof."
Should be
"Although BOOST_SCOPE_EXIT_TPL has the same suffix as BOOST_TYPEOF_TPL,
it doesn't follow the convention of Boost.Typeof."

impl.html:

"but some requirements made implementation a bit more complicated:"
Should be
"but some requirements made the implementation a bit more complicated:"

"Doing this would change a code starting from a definition of the
scope_exit_t_1 struct in the following way:"
Should be
"Doing this would change the code starting from the definition of the
scope_exit_t_1 struct to the following:"

In Christ,
Steven Watanabe