[Runtime][Stdlib][Overlays] Add comments to all the renamed classes explaining the rename and noting that the old name cannot be used due to conflicts.

rdar://problem/35768222

Author: mikeash

stdlib/public/SDK/Foundation/Data.swift

@@ -966,6 +966,9 @@ internal final class _DataStorage {
     }
 }
 
+// NOTE: older runtimes called this _NSSwiftData. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 internal class __NSSwiftData : NSData {
     var _backing: _DataStorage!
     var _range: Range<Data.Index>!

stdlib/public/SDK/Foundation/NSObject.swift

@@ -45,12 +45,15 @@ fileprivate extension NSObject {
 
 }
 
+// NOTE: older overlays called this _KVOKeyPathBridgeMachinery. The two
+// must coexist, so it was renamed. The old name must not be used in the
+// new runtime.
 @objc private class __KVOKeyPathBridgeMachinery : NSObject {
     @nonobjc static var keyPathTable: [String : AnyKeyPath] = {
         /*
          Move all our methods into place. We want the following:
          __KVOKeyPathBridgeMachinery's automaticallyNotifiesObserversForKey:, and keyPathsForValuesAffectingValueForKey: methods replaces NSObject's versions of them
-         NSObject's automaticallyNotifiesObserversForKey:, and keyPathsForValuesAffectingValueForKey: methods replace NSObject's _old_unswizzled_* methods
+         NSObject's automaticallyNotifiesObserversForKey:, and keyPathsForValuesAffectingValueForKey: methods replace NSObject's __old_unswizzled_* methods
          NSObject's _old_unswizzled_* methods replace __KVOKeyPathBridgeMachinery's methods, and are never invoked
          */
         let rootClass: AnyClass = NSObject.self
@@ -64,7 +67,7 @@ fileprivate extension NSObject {
         let originalDependentImpl = class_getClassMethod(bridgeClass, dependentSel)! //we swizzled it onto this class, so this is actually NSObject's old implementation
         let originalDependentSel = #selector(NSObject.__old_unswizzled_keyPathsForValuesAffectingValue(forKey:))
         let dummyDependentImpl = class_getClassMethod(rootClass, originalDependentSel)!
-        method_exchangeImplementations(originalDependentImpl, dummyDependentImpl) // NSObject's original version <-> NSObject's _old_unswizzled_ version
+        method_exchangeImplementations(originalDependentImpl, dummyDependentImpl) // NSObject's original version <-> NSObject's __old_unswizzled_ version
 
         let autoSel = #selector(NSObject.automaticallyNotifiesObservers(forKey:))
         let rootAutoImpl = class_getClassMethod(rootClass, autoSel)!
@@ -74,7 +77,7 @@ fileprivate extension NSObject {
         let originalAutoImpl = class_getClassMethod(bridgeClass, autoSel)! //we swizzled it onto this class, so this is actually NSObject's old implementation
         let originalAutoSel = #selector(NSObject.__old_unswizzled_automaticallyNotifiesObservers(forKey:))
         let dummyAutoImpl = class_getClassMethod(rootClass, originalAutoSel)!
-        method_exchangeImplementations(originalAutoImpl, dummyAutoImpl) // NSObject's original version <-> NSObject's _old_unswizzled_ version
+        method_exchangeImplementations(originalAutoImpl, dummyAutoImpl) // NSObject's original version <-> NSObject's __old_unswizzled_ version
 
         return [:]
     }()
@@ -128,6 +131,9 @@ func _bridgeStringToKeyPath(_ keyPath:String) -> AnyKeyPath? {
     return __KVOKeyPathBridgeMachinery._bridgeKeyPath(keyPath)
 }
 
+// NOTE: older overlays called this NSKeyValueObservation. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 public class _NSKeyValueObservation : NSObject {
 
     @nonobjc weak var object : NSObject?

stdlib/public/SDK/SpriteKit/SpriteKit.swift

@@ -24,6 +24,10 @@ public typealias SKColor = UIColor
 // this class only exists to allow AnyObject lookup of _copyImageData
 // since that method only exists in a private header in SpriteKit, the lookup
 // mechanism by default fails to accept it as a valid AnyObject call
+//
+// NOTE: older runtimes called this _SpriteKitMethodProvider. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 @objc class __SpriteKitMethodProvider : NSObject {
   override init() { preconditionFailure("don't touch me") }
   @objc func _copyImageData() -> NSData! { return nil }

stdlib/public/core/ContiguousArrayBuffer.swift

@@ -17,6 +17,10 @@ import SwiftShims
 /// initialized.  See stdlib/runtime/GlobalObjects.cpp for details.
 /// Because it's statically referenced, it requires non-lazy realization
 /// by the Objective-C runtime.
+///
+/// NOTE: older runtimes called this _EmptyArrayStorage. The two must
+/// coexist, so it was renamed. The old name must not be used in the new
+/// runtime.
 @_fixed_layout
 @usableFromInline
 @_objc_non_lazy_realization

stdlib/public/core/Dictionary.swift

@@ -1804,6 +1804,10 @@ internal protocol _DictionaryBuffer {
 // NOTE: The precise layout of this type is relied on in the runtime
 // to provide a statically allocated empty singleton.
 // See stdlib/public/stubs/GlobalObjects.cpp for details.
+//
+// NOTE: older runtimes called this _RawNativeDictionaryStorage. The two
+// must coexist, so it was renamed. The old name must not be used in the
+// new runtime.
 @_fixed_layout // FIXME(sil-serialize-all)
 @usableFromInline
 @_objc_non_lazy_realization

stdlib/public/core/Runtime.swift.gyb

@@ -484,6 +484,10 @@ internal func _rawPointerToString(_ value: Builtin.RawPointer) -> String {
 // The @swift_native_objc_runtime_base attribute
 // allows us to subclass an Objective-C class and still use the fast Swift
 // memory allocator.
+//
+// NOTE: older runtimes called these _SwiftNativeNSXXX. The two must
+// coexist, so they were renamed. The old names must not be used in the
+// new runtime.
 
 @_fixed_layout // FIXME(sil-serialize-all)
 @usableFromInline // FIXME(sil-serialize-all)

stdlib/public/core/Set.swift

@@ -1407,6 +1407,10 @@ internal protocol _SetBuffer { // FIXME: Remove or refactor for Set.
 // NOTE: The precise layout of this type is relied on in the runtime
 // to provide a statically allocated empty singleton.
 // See stdlib/public/stubs/GlobalObjects.cpp for details.
+//
+// NOTE: older runtimes called this _RawNativeSetStorage. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 @_fixed_layout // FIXME(sil-serialize-all)
 @usableFromInline
 @_objc_non_lazy_realization

stdlib/public/core/StringBridge.swift

@@ -223,6 +223,10 @@ extension String {
 // The @_swift_native_objc_runtime_base attribute
 // This allows us to subclass an Objective-C class and use the fast Swift
 // memory allocator.
+//
+// NOTE: older runtimes called this _SwiftNativeNSString. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 @_fixed_layout // FIXME(sil-serialize-all)
 @objc @_swift_native_objc_runtime_base(__SwiftNativeNSStringBase)
 public class __SwiftNativeNSString {
@@ -260,6 +264,10 @@ public protocol _NSStringCore : _NSCopying /* _NSFastEnumeration */ {
 }
 
 /// An `NSString` built around a slice of contiguous Swift `String` storage.
+///
+/// NOTE: older runtimes called this _NSContiguousString. The two must
+/// coexist, so it was renamed. The old name must not be used in the new
+/// runtime.
 @_fixed_layout // FIXME(sil-serialize-all)
 public final class __NSContiguousString : __SwiftNativeNSString, _NSStringCore {
   public let _guts: _StringGuts

stdlib/public/core/SwiftNativeNSArray.swift

@@ -37,6 +37,10 @@ internal func _isValidArraySubscript(_ index: Int, count: Int) -> Bool {
 
 /// An `NSArray` with Swift-native reference counting and contiguous
 /// storage.
+///
+/// NOTE: older runtimes called this
+/// _SwiftNativeNSArrayWithContiguousStorage. The two must coexist, so
+/// it was renamed. The old name must not be used in the new runtime.
 @_fixed_layout // FIXME(sil-serialize-all)
 @usableFromInline
 internal class __SwiftNativeNSArrayWithContiguousStorage
@@ -261,6 +265,10 @@ internal class __SwiftNativeNSArrayWithContiguousStorage {
 #endif
 
 /// Base class of the heap buffer backing arrays.  
+///
+/// NOTE: older runtimes called this _ContiguousArrayStorageBase. The
+/// two must coexist, so it was renamed. The old name must not be used
+/// in the new runtime.
 @usableFromInline
 @_fixed_layout
 internal class __ContiguousArrayStorageBase

stdlib/public/runtime/ErrorObject.mm

@@ -45,6 +45,10 @@
 /// A subclass of NSError used to represent bridged native Swift errors.
 /// This type cannot be subclassed, and should not ever be instantiated
 /// except by the Swift runtime.
+///
+/// NOTE: older runtimes called this _SwiftNativeNSError. The two must
+/// coexist, so it was renamed. The old name must not be used in the new
+/// runtime.
 @interface __SwiftNativeNSError : NSError
 @end
 

stdlib/public/runtime/SwiftValue.mm

@@ -45,6 +45,10 @@
 // - object header,
 // - `SwiftValueHeader` instance,
 // - the payload, tail-allocated (the Swift value contained in this box).
+//
+// NOTE: older runtimes called this _SwiftValue. The two must
+// coexist, so it was renamed. The old name must not be used in the new
+// runtime.
 @interface __SwiftValue : NSObject <NSCopying>
 
 - (id)copyWithZone:(NSZone *)zone;

stdlib/public/stubs/OptionalBridgingHelper.mm

@@ -26,6 +26,10 @@
 
 /// Class of sentinel objects used to represent the `nil` value of nested
 /// optionals.
+///
+/// NOTE: older runtimes called this _SwiftNull. The two must
+/// coexist, so it was renamed. The old name must not be used in the new
+/// runtime.
 @interface __SwiftNull : NSObject {
 @public
   unsigned depth;

stdlib/public/stubs/SwiftNativeNSXXXBase.mm.gyb

@@ -49,6 +49,9 @@ extern "C" CFHashCode CFStringHashCString(const uint8_t *bytes, CFIndex len);
 
 using namespace swift;
 
+// NOTE: older runtimes called these _SwiftNativeNSXXXBase. The two must
+// coexist, so these were renamed. The old names must not be used in the new
+// runtime.
 % for Class in ('Array', 'Dictionary', 'Set', 'String', 'Enumerator', 'Data', 'IndexSet'):
 SWIFT_RUNTIME_STDLIB_API
 @interface __SwiftNativeNS${Class}Base : NS${Class}