Re: [boost] Review Request: Boost Exception

From: David Abrahams (dave_at_[hidden])
Date: 2006-11-13 10:40:54

"Emil Dotchevski" <emildotchevski_at_[hidden]> writes:

> I believe the proposed Boost Exception library is now mature enough for 
> formal review.
>
> Please read the documentation at:
>
> http://www.revergestudios.com/boost-exception/boost-exception.htm

The introduction reveals some problems

1. The first sentence is very confusing and gives the strong
   impression of being completely circular.

    "The main motivation for using exception handling is that when
     writing exception-safe code, the vast majority of contexts in the
     program are exception-neutral."

   That's like saying,

      "the main motivation for using a hammer is that, when hammering,
       the vast majority of contexts require driving a nail."

2. The second sentence begins with "But."  Although gaining currency,
   mostly for informal writing, that's still not considered correct in
   most circles.

3. "The semantics of exception handling suggest throwing unnamed
   temporary objects,..."  

   They do?  How so?

   "...therefore, the throw site needs to have all the information
   relevant to the failure"

   The 2nd part doesn't follow from the first part.

4. In the 3rd paragraph, "which" should be "that"

Finally, in the 3rd paragraph, you tell me what this library does.
That part makes sense.  I suggest you:

 * figure out what you mean to say in the introduction
 * write it first as a series of terse bullets
 * do not attempt to give background about EH in general
 
Then you can translate these bullets into prose.  The introduction
will probably end up being just a few sentences long.

The first example uses "error_info_value" without qualification.  You
need to test your examples.  If you write your documentation using
ReStructuredText, you can use the system we use for the parameter
library, in tools/litre.  No comparable system exists for boostbook
today; you'll have to build one or test the examples by hand.

Finally, a design note: I don't like the fact that I need a try/catch
block in order to adorn the currently-unwinding exception with more
information; it's just too heavy syntactically.  I realize it would
require TLS for thread-safety, but I'd like to see an option that uses
the destructor of a local object to do the same work.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com