Merge pull request #36955 from mininny/add-dynamic-subclass-kvo-doc

Author: swift-ci

include/swift/ABI/Metadata.h

@@ -1168,8 +1168,25 @@ struct TargetClassMetadata : public TargetAnyClassMetadata<Runtime> {
     Description = description;
   }
 
+  // [NOTE: Dynamic-subclass-KVO]
+  //
+  // Using Objective-C runtime, KVO can modify object behavior without needing
+  // to modify the object's code. This is done by dynamically creating an
+  // artificial subclass of the the object's type.
+  //
+  // The isa pointer of the observed object is swapped out to point to
+  // the artificial subclass, which has the following properties:
+  // - Setters for observed keys are overridden to additionally post
+  // notifications.
+  // - The `-class` method is overridden to return the original class type
+  // instead of the artificial subclass type.
+  //
+  // For more details, see:
+  // https://www.mikeash.com/pyblog/friday-qa-2009-01-23.html
+
   /// Is this class an artificial subclass, such as one dynamically
   /// created for various dynamic purposes like KVO?
+  /// See [NOTE: Dynamic-subclass-KVO]
   bool isArtificialSubclass() const {
     assert(isTypeMetadata());
     return Description == nullptr;

include/swift/RemoteAST/RemoteAST.h

@@ -184,11 +184,11 @@ class RemoteASTContext {
   /// resolve it to a specific type in the local AST.
   ///
   /// \param skipArtificial If true, the address may be an artificial type
-  ///   wrapper that should be ignored.  For example, it could be a
+  ///   wrapper that should be ignored. For example, it could be a
   ///   dynamic subclass created by (e.g.) CoreData or KVO; if so, and this
   ///   flag is set, this method will implicitly ignore the subclass
   ///   and instead attempt to resolve a type for the first non-artificial
-  ///   superclass.
+  ///   superclass. See [NOTE: Dynamic-subclass-KVO].
   Result<Type>
   getTypeForRemoteTypeMetadata(remote::RemoteAddress address,
                                bool skipArtificial = false);

include/swift/Runtime/Casting.h

@@ -224,7 +224,7 @@ swift_getDynamicType(OpaqueValue *value, const Metadata *self,
 /// Fetch the type metadata associated with the formal dynamic
 /// type of the given (possibly Objective-C) object.  The formal
 /// dynamic type ignores dynamic subclasses such as those introduced
-/// by KVO.
+/// by KVO. See [NOTE: Dynamic-subclass-KVO]
 ///
 /// The object pointer may be a tagged pointer, but cannot be null.
 SWIFT_RUNTIME_EXPORT

stdlib/public/runtime/Metadata.cpp

@@ -385,6 +385,7 @@ static GenericMetadataCache &getCache(
 }
 
 #if SWIFT_PTRAUTH && SWIFT_OBJC_INTEROP
+// See [NOTE: Dynamic-subclass-KVO]
 static void swift_objc_classCopyFixupHandler(Class oldClass, Class newClass) {
   auto oldClassMetadata = reinterpret_cast<const ClassMetadata *>(oldClass);