I have more than once reported to Apple that their document section
Document-Based App Programming Guide for Mac
Alternative Design Considerations
Message Flow in the Document Architecture
Saving A Document
has given incorrect information since Mac OS X 10.7 was released in 2011. As of this writing (2013-10-30), it is still incorrect. Let this blog post serve as an errata until they rewrite it.
The section Document-Based App Programming Guide for Mac > Alternative Design Considerations > Message Flow in the Document Architecture > Saving a Document has been incorrect since Lion was released. Some of the errors are obvious - step 4 refers to method
saveToURL:
ofType:
forSaveOperation:
delegate:
didSaveSelector:
contextInfo:
This method is depracated, no longer used and does not appear in the diagram.
But more importantly, the timeline (colored rectangles) along the left side of the graphic indicate that these methods invoke one another in a conventional "stack". But that is not what happens any more. Since 10.7, some of these methods return and only later are the methods higher in the stack (actually more "rightmost" because the time axis on this diagram is downward) invoked by the "perform synchronous activity" magic.
It is important for developers to know, for example, when it is safe to assume that a document has been written in the disk, and I'd really appreciate it if someone could explain the "perform synchronous activity" magic, which somehow allows methods to return, and then more work is performed on the same thread. Are they queued in the run loop somehow? Dispatched in blocks?
Just as important, we need another, new diagram to show when and how Auto Save works.
And finally, there is no mention of Asynchronous vs. old style saving. Apparently, only the old style is shown. A new diagram needs to be added for Asynchronous Saving.