This is part of exception handling, which the group has found tricky to discuss and design. Decorations are the means we chose; subsequent discussions show it is not easy to grasp how to use them properly. George Corliss (2010 Aug 29) wrote
If folks of OUR experience have trouble understanding, God help the casual user!
We have been, and we must continue to be, sensitive to KISS. I guess one path to
simplicity is a very carefully worked-out, consistent, and coherent level model.
That is, WE work very hard so that the result is easy.
I’m OK with that, as long as the result IS easy.
This made me think, rightly or wrongly, that it is crucial to be able to _explain_ discont to a prospective user, i.e. a writer of application software. So this version, V3, is a complete rewrite of V2 with that in mind. In Subsection 3.2, I attempt to document discont for such a user. Please read this critically. Does it explain the existing design simply enough? Could the design be changed to fulfil the same purpose but simplify the explanation?