Clarify the point at which ARC destroys ivars vis-à-vis
[super dealloc].  rdar://problem/11141872

git-svn-id: 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html
index 2fd82dd..5cacbd5 100644
--- a/docs/AutomaticReferenceCounting.html
+++ b/docs/AutomaticReferenceCounting.html
@@ -1611,6 +1611,36 @@
 that <tt>NSObject</tt>'s <tt>dealloc</tt> would, which is outside the
 scope of this document to describe.</p></div>
+<p>The instance variables for an ARC-compiled class will be destroyed
+at some point after control enters the <tt>dealloc</tt> method for the
+root class of the class.  The ordering of the destruction of instance
+variables is unspecified, both within a single class and between
+subclasses and superclasses.</p>
+<div class="rationale"><p>Rationale: the traditional, non-ARC pattern
+for destroying instance variables is to destroy them immediately
+before calling <tt>[super&nbsp;dealloc]</tt>.  Unfortunately, message
+sends from the superclass are quite capable of reaching methods in the
+subclass, and those methods may well read or write to those instance
+variables.  Making such message sends from dealloc is generally
+discouraged, since the subclass may well rely on other invariants that
+were broken during <tt>dealloc</tt>, but it's not so inescapably
+dangerous that we felt comfortable calling it undefined behavior.
+Therefore we chose to delay destroying the instance variables to a
+point at which message sends are clearly disallowed: the point at
+which the root class's deallocation routines take over.</p>
+<p>In most code, the difference is not observable.  It can, however,
+be observed if an instance variable holds a strong reference to an
+object whose deallocation will trigger a side-effect which must be
+carefully ordered with respect to the destruction of the super class.
+Such code violates the design principle that semantically important
+behavior should be explicit.  A simple fix is to clear the instance
+variable manually during <tt>dealloc</tt>; a more holistic solution is
+to move semantically important side-effects out of
+<tt>dealloc</tt> and into a separate teardown phase which can rely on
+working with well-formed objects.</p></div>
 </div> <!-- misc.special_methods -->