As a step toward improving matters, I've attached the suggested doc patch (for both 25-maint and trunk).  It encourages people to use Maildir :), explicitly states that modifications should be bracketed by lock(), and fixes the examples to match.

It does not say that keys are invalidated by doing a flush(), because we're going to try to avoid the necessity for that.


File Added: mailbox-docs.diff