[doc] Reduce the length of the docs

Author: mininny

include/swift/ABI/Metadata.h

@@ -1168,28 +1168,25 @@ struct TargetClassMetadata : public TargetAnyClassMetadata<Runtime> {
     Description = description;
   }
 
-  /// 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.
+  // 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.
   //
-  // 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.
+  // 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;

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. See [NOTE: Dynamic-subclass-KVO]
+/// by 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. See [NOTE: Dynamic-subclass-KVO]
+/// by KVO.
 ///
 /// The object pointer may be a tagged pointer, but cannot be null.
 const Metadata *swift::swift_getObjectType(HeapObject *object) {