[nfc][cxx-interop] Add a few comments and asserts

Author: zoecarver

include/swift/ABI/Metadata.h

@@ -1164,6 +1164,16 @@ struct TargetForeignClassMetadata : public TargetForeignTypeMetadata<Runtime> {
 };
 using ForeignClassMetadata = TargetForeignClassMetadata<InProcess>;
 
+/// The structure of metadata objects for foreign reference types.
+/// A foreign reference type is a non-Swift, non-Objective-C foreign type with
+/// reference semantics. Foreign reference types are pointers/reference to
+/// value types marked with the "import_as_ref" attribute.
+///
+/// Foreign reference types may have *custom* reference counting operations, or
+/// they may be immortal (and therefore trivial).
+///
+/// We assume for now that foreign reference types are entirely opaque
+/// to Swift introspection.
 template <typename Runtime>
 struct TargetForeignReferenceTypeMetadata : public TargetForeignTypeMetadata<Runtime> {
   using StoredPointer = typename Runtime::StoredPointer;

include/swift/ABI/MetadataKind.def

@@ -53,6 +53,7 @@ NOMINALTYPEMETADATAKIND(Optional, 2 | MetadataKindIsNonHeap)
 /// A foreign class, such as a Core Foundation class.
 METADATAKIND(ForeignClass, 3 | MetadataKindIsNonHeap)
 
+/// A non-Swift non-Objective-C class type.
 METADATAKIND(ForeignReferenceType, 4 | MetadataKindIsNonHeap)
 
 /// A type whose value is not exposed in the metadata system.

lib/IRGen/GenMeta.cpp

@@ -1787,8 +1787,7 @@ namespace {
       // is a foreign class.
       if ((IGM.IRGen.Opts.ReflectionMetadata !=
            ReflectionMetadataMode::Runtime) ||
-          getType()->isForeign() ||
-          getType()->isForeignReferenceType()) {
+          getType()->isForeign()) {
         B.addInt32(0);
         return;
       }
@@ -5430,6 +5429,9 @@ namespace {
     ForeignClassMetadataBuilder(IRGenModule &IGM, ClassDecl *target,
                                 ConstantStructBuilder &B)
         : ForeignMetadataBuilderBase(IGM, target, B) {
+      assert(!getTargetType()->isForeignReferenceType() &&
+             "foreign reference type metadata must be built with the ForeignReferenceTypeMetadataBuilder");
+
       if (IGM.getOptions().LazyInitializeClassMetadata)
         CanBeConstant = false;
     }
@@ -5559,11 +5561,6 @@ namespace {
     }
 
     void addSuperclass() {
-      // Always leave the superclass pointer unfilled.  We'll have to
-      // unique it during initialization anyway, so we might as well spare
-      // ourselves the load-time work.
-      B.addNullPointer(IGM.TypeMetadataPtrTy);
-
       assert(!Target->hasSuperclass() &&
              "foreign reference types should not have superclasses.");
     }