David Abrahams wrote:
[...] 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.
I would just make the editorial fixes as so: ...the library maintains its invariants...
- 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.
Looks good.
- ...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?
I think it's a good idea overall, and perhaps some older libraries that don't document exception safety should revisit the issue. The library requirements page mentions "Discussion of error detection and recovery strategy", but doesn't require any particular section to be in the documentation. Perhaps we should require that libraries that offer something other than the basic guarantee include an exception safety section in the docs. Dave