[docs] Add short note about dynamic subclassing and KVO

Author: mininny

include/swift/ABI/Metadata.h

@@ -1170,6 +1170,26 @@ struct TargetClassMetadata : public TargetAnyClassMetadata<Runtime> {
 
   /// Is this class an artificial subclass, such as one dynamically
   /// created for various dynamic purposes like KVO?
+  //
+  // [NOTE: Dynamic-subclass-KVO]
+  // To implement Key-Value Observing without any code that notifies the
+  // observer, the KVO infrastructure uses dynamic subclassing with Objective-C
+  // runtime. When a variable is observed, KVO creates a secret dynamic subclass
+  // of that class under the hood which are defined with a prefix of
+  // `NSKVONotifying_`.
+  //
+  // While the observed variables have the type of the dynamic subclass, they
+  // must appear like their non-observed counterparts for the front-end user. To
+  // achieve this, the dynamic subclass overrides `-class` method which returns
+  // the original class type, and internally refers to the subclass in the
+  // runtime.
+  //
+  // In the created subclass, `-set` methods for observed variables are
+  // overridden, where the calls to the observer notifications are triggered.
+  // KVO only generates one dynamic subclass for each class which overrides all
+  // setter methods of variables being observed. That is, setters of variables
+  // that are not observed are also not overridden in the dynamic subclass for
+  // efficiency.
   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);
 

stdlib/public/runtime/SwiftObject.mm

@@ -92,7 +92,7 @@ static Class _swift_getObjCClassOfAllocated(const void *object) {
 /// Fetch the ObjC class object 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.
 const ClassMetadata *swift::swift_getObjCClassFromObject(HeapObject *object) {
@@ -122,7 +122,7 @@ static Class _swift_getObjCClassOfAllocated(const void *object) {
 /// 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.
 const Metadata *swift::swift_getObjectType(HeapObject *object) {