Hi, On Sat, Jul 17, 2004 at 08:31:07AM -0400, David Abrahams wrote: [snip]
No, you just follow the established practice for documenting exception-safety in generic functions. There's no need to reinvent the wheel.
I think purity is a useful idea for analyzing exception safety, and I have no objection to mentioning it in specifications _if_ it truly adds clarity. If the specification can be considered minimal and complete without mentioning purity, that might be better.
It might be best to describe what it means to say "has no effects" in one place. Maybe I should put a section in http://www.boost.org/more/error_handling.html that discusses these conventions for documenting exception-safety. Then library documentation can link to that part of the page. It would say something like:
- Unless otherwise specified, all Boost library operations give the /basic guarantee/: the library's maintains its invariants and does not leak resources in the face of exceptions.
- Some library operations give the /strong guarantee/ that if an exception is thrown, there are no effects. If those operations involve calls to user-supplied operations (such as copying an instance of a template type parameter) and those operations have side-effects, it's understood that those side-effects are outside the control of the library and not included in the strong guarantee.
- ...anything else...?
Then I would probably add a section that showed some examples of the kind of language used to document exception-safety, and describe how to understand it.
Thoughts?
For me, this seems rather fine. I have tried to sumarize something similar in <http://tinyurl.com/3wgvu>. I thinks, that overspecification is not very useful. Detailed definition what operations are reguired to have which guarantee for each function is nice for library correctness checking, but not for an average user. Regards, Pavol