When documenting members of extensions to external protocols, display the external protocol's name (#732)

rdar://112219546

When documenting members of extensions to external protocols, display
the external protocol's name. This is helpful because these pages don’t
have the context of being curated inside their “owning” type or
protocol.

Expand the section that we use for conditional constraints to display
the external protocol name, for example: "Self is ExternalProtocol". The
new "Self is ExternalProtocol" message will be combined with any other
existing generic constraints. Do not do this for extended structs,
classes or other extended types, since this generic constraint syntax
wouldn't be accurate for them.

Also as a related bug fix remove the extendedModule property of the
Semanic Symbol class, and instead calculate this based on
swiftExtensionVariants. Same for constraintsVariants. Fix the
initializer of Semantic Symbol, which previously allowed a nil default
value for the extendedModule property, allowing callers to accidentally
leave it nil.

Author: patshaughnessy

Package.resolved

@@ -1411,7 +1411,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         }
     }
 
-    
+
     /// Builds in-memory relationships between symbols based on the relationship information in a given symbol graph file.
     ///
     /// - Parameters:
@@ -1427,8 +1427,22 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         bundle: DocumentationBundle,
         engine: DiagnosticEngine
     ) {
+
+        // Find all of the relationships which refer to an extended module.
+        let extendedModuleRelationships = ExtendedTypeFormatTransformation.collapsedExtendedModuleRelationships(from: relationships)
+
         for edge in relationships {
             switch edge.kind {
+            case .memberOf, .optionalMemberOf:
+                // Add a "Self is" constraint for members of protocol extensions that
+                // extend a protocol from extended modules.
+                SymbolGraphRelationshipsBuilder.addProtocolExtensionMemberConstraint(
+                    edge: edge,
+                    selector: selector,
+                    extendedModuleRelationships: extendedModuleRelationships,
+                    symbolIndex: &symbolIndex,
+                    documentationCache: documentationCache
+                )
             case .conformsTo:
                 // Build conformant type <-> protocol relationships
                 SymbolGraphRelationshipsBuilder.addConformanceRelationship(

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -184,6 +184,50 @@ extension ExtendedTypeFormatTransformation {
         return true
     }
 
+    // Collapse inContextOf relationships into their target declaredIn
+    // relationships. See the diagram above. Return a dictionary of source
+    // identifiers to the target identifiers.
+    typealias SourceIdentifier = String
+    typealias TargetIdentifier = String
+    static func collapsedExtendedModuleRelationships(from relationships: Set<SymbolGraph.Relationship>) -> [ SourceIdentifier : TargetIdentifier] {
+
+        // Filter all the relationships down to only declaredIn and inContextOf.
+        let filtered = relationships.filter { $0.kind == .declaredIn || $0.kind == .inContextOf }
+
+        // Create a dictionary of relationships by their source identifier, to
+        // speed up lookup below.
+        let relsBySource = filtered.reduce(into: [:]) { result, rel in
+            result[rel.source] = rel
+        }
+
+        // Reduce the filtered list and build up a dictionary of:
+        // - key = original source symbol
+        // - value = target of declaredIn = which external module the symbol was
+        //           declared in.
+        return filtered.reduce(into: [:]) { result, relationship in
+            var rel = relationship
+            var seen: Set<String> = []
+            // Walk the target->relationship hierarchy until we find declaredIn
+            while rel.kind != .declaredIn {
+                // Stop if we encounter a cycle in the hierarchy
+                guard !seen.contains(rel.source) else {
+                    return
+                }
+                seen.insert(rel.source)
+                // Look up the target relationship in the dictionary created
+                // above. Stop if not found.
+                guard let r = relsBySource[rel.target] else {
+                    return
+                }
+                // Step to the target relationship looking for
+                // declaredIn.
+                rel = r
+            }
+            // Save the original source as the key to the declaredIn target
+            result[relationship.source] = rel.target
+        }
+    }
+
     /// Tries to obtain `docComment`s for all `targets` and copies the documentation from sources to the target.
     ///
     /// Iterates over all `targets` calling the `source` method to obtain a list of symbols that should serve as sources for the target's `docComment`.

Sources/SwiftDocC/Infrastructure/Symbol Graph/ExtendedTypeFormatTransformation.swift

@@ -396,5 +396,80 @@ struct SymbolGraphRelationshipsBuilder {
             setAsInheritedSymbol(origin: origin, for: &context.documentationCache[reference]!, originNode: symbolIndex[origin.identifier].flatMap { context.documentationCache[$0] })
         }
     }
-}
 
+    /// Add a new generic constraint: "Self is SomeProtocol" to members of
+    /// protocol extensions of protocols from external modules. When a protocol
+    /// is defined in a different module it's not clear which protocol the
+    /// extension is for since we don't otherwise display that, unless implied
+    /// by curation.
+    ///
+    /// - Parameters:
+    ///   - edge: A symbol graph relationship with a source and a target.
+    ///   - selector: The symbol graph selector in which the relationship is
+    ///     relevant.
+    ///   - extendedModuleRelationships: Source->target dictionary for external
+    ///     module relationships.
+    ///   - symbolIndex: A symbol lookup map by precise identifier.
+    ///   - documentationCache: A documentation node lookup by the node's resolved reference.
+
+    static func addProtocolExtensionMemberConstraint(
+        edge: SymbolGraph.Relationship,
+        selector: UnifiedSymbolGraph.Selector,
+        extendedModuleRelationships: [String : String],
+        symbolIndex: inout [String: ResolvedTopicReference],
+        documentationCache: [ResolvedTopicReference: DocumentationNode]
+    ) {
+
+        // Utility function to look up a symbol identifier in the
+        // symbol index, returning its documentation node and semantic symbol
+        func nodeAndSymbolFor(identifier: String) -> (DocumentationNode, Symbol)? {
+            if let node = symbolIndex[identifier].flatMap({documentationCache[$0]}),
+               let symbol = node.semantic as? Symbol {
+                return (node, symbol)
+            }
+            return nil
+        }
+
+        // Is this symbol a member of some type from an extended module?
+        guard let extendedModuleRelationship = extendedModuleRelationships[edge.target] else {
+            return
+        }
+
+        // Return unless the target symbol is a protocol. The "Self is ..."
+        // constraint only makes sense for protocol extensions.
+        guard let (targetNode, targetSymbol) = nodeAndSymbolFor(identifier: edge.target) else {
+            return
+        }
+        guard targetNode.kind == .extendedProtocol else {
+            return
+        }
+
+        // Obtain the source symbol
+        guard let (_, sourceSymbol) = nodeAndSymbolFor(identifier: edge.source) else {
+            return
+        }
+
+        // Obtain the extended module documentation node.
+        guard let (_, extendedModuleSymbol) = nodeAndSymbolFor(identifier: extendedModuleRelationship) else {
+            return
+        }
+
+        // Create a new generic constraint: "Self is SomeProtocol" to show which
+        // protocol this function's extension is extending.  When the protocol is
+        // defined in a different module it's not clear at all which protocol it
+        // is, especially if the curation doesn't indicate that.
+        let newConstraint = SymbolGraph.Symbol.Swift.GenericConstraint(
+            kind: SymbolGraph.Symbol.Swift.GenericConstraint.Kind.sameType,
+            leftTypeName: "Self",
+            rightTypeName: targetSymbol.title
+        )
+
+        // Add the constraint to the source symbol, the member of the protocol
+        // extension.
+        sourceSymbol.addSwiftExtensionConstraint(
+            extendedModule: extendedModuleSymbol.title,
+            extendedSymbolKind: .protocol,
+            constraint: newConstraint
+        )
+    }
+}

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphRelationshipsBuilder.swift

@@ -239,10 +239,6 @@ public struct DocumentationNode {
 
         self.availableSourceLanguages = reference.sourceLanguages
 
-        let extendedModule: String? = unifiedSymbol.mixins
-            .first(where: { $0.0.platform == platformName })?.value
-            .getValueIfPresent(for: SymbolGraph.Symbol.Swift.Extension.self)?.extendedModule
-        
         let semanticSymbol = Symbol(
             kindVariants: DocumentationDataVariants(
                 symbolData: unifiedSymbol.kind,
@@ -272,7 +268,6 @@ public struct DocumentationNode {
                 defaultVariantValue: platformName.map(PlatformName.init(operatingSystemName:))
             ),
             moduleReference: moduleReference,
-            extendedModule: extendedModule,
             externalIDVariants: DocumentationDataVariants(defaultVariantValue: unifiedSymbol.uniqueIdentifier),
             accessLevelVariants: DocumentationDataVariants(
                 symbolData: unifiedSymbol.accessLevel,

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -1198,13 +1198,27 @@ public struct RenderNodeTranslator: SemanticVisitor {
 
         if let crossImportOverlayModule = symbol.crossImportOverlayModule {
             node.metadata.modulesVariants = VariantCollection(defaultValue: [RenderMetadata.Module(name: crossImportOverlayModule.declaringModule, relatedModules: crossImportOverlayModule.bystanderModules)])
-        } else if let extendedModule = symbol.extendedModule, extendedModule != moduleName.displayName {
-            node.metadata.modulesVariants = VariantCollection(defaultValue: [RenderMetadata.Module(name: moduleName.displayName, relatedModules: [extendedModule])])
+
+        } else if let moduleVariants = VariantCollection<[RenderMetadata.Module]?>(
+            from: symbol.extendedModuleVariants,
+            transform: { (_, value) in
+                let relatedModules: [String]?
+                if value != moduleName.displayName {
+                    relatedModules = [value]
+                } else {
+                    relatedModules = nil
+                }
+                return [
+                    RenderMetadata.Module(name: moduleName.displayName, relatedModules: relatedModules)
+                ]
+            }
+        ) {
+            node.metadata.modulesVariants = moduleVariants
         } else {
             node.metadata.modulesVariants = VariantCollection(defaultValue: [RenderMetadata.Module(name: moduleName.displayName, relatedModules: nil)])
         }
-        
-        node.metadata.extendedModuleVariants = VariantCollection<String?>(defaultValue: symbol.extendedModule)
+
+        node.metadata.extendedModuleVariants = VariantCollection<String?>(from: symbol.extendedModuleVariants)
 
         node.metadata.platformsVariants = VariantCollection<[AvailabilityRenderItem]?>(from: symbol.availabilityVariants) { _, availability in
             availability.availability

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -480,7 +480,6 @@ struct ReferenceResolver: SemanticVisitor {
             roleHeadingVariants: symbol.roleHeadingVariants,
             platformNameVariants: symbol.platformNameVariants,
             moduleReference: symbol.moduleReference,
-            extendedModule: symbol.extendedModule,
             requiredVariants: symbol.isRequiredVariants,
             externalIDVariants: symbol.externalIDVariants,
             accessLevelVariants: symbol.accessLevelVariants,

Sources/SwiftDocC/Semantics/ReferenceResolver.swift

@@ -29,7 +29,7 @@ import SymbolKit
 /// - ``kindVariants``
 /// - ``platformNameVariants``
 /// - ``moduleReference``
-/// - ``extendedModule``
+/// - ``extendedModuleVariants``
 /// - ``bystanderModuleNames``
 /// - ``isRequiredVariants``
 /// - ``externalIDVariants``
@@ -115,9 +115,15 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
 
     /// The reference to the documentation node that represents this symbol's module symbol.
     internal(set) public var moduleReference: ResolvedTopicReference
-    
-    /// The name of the module extension in which the symbol is defined, if applicable.
-    internal(set) public var extendedModule: String?
+
+    /// The name of the module extension in which the symbol is defined, in each language variant the symbol is available in
+    public var extendedModuleVariants: DocumentationDataVariants<String> {
+        var variants = DocumentationDataVariants<String>()
+        for (trait, swiftExtension) in swiftExtensionVariants() {
+            variants[trait] = swiftExtension.extendedModule
+        }
+        return variants
+    }
 
     /// The names of any "bystander" modules required for this symbol, if it came from a cross-import overlay.
     @available(*, deprecated, message: "Use crossImportOverlayModule instead")
@@ -146,10 +152,16 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
     )
 
     public var locationVariants = DocumentationDataVariants<SymbolGraph.Symbol.Location>()
-    
+
     /// The symbol's availability or conformance constraints, in each language variant the symbol is available in.
-    public var constraintsVariants = DocumentationDataVariants<[SymbolGraph.Symbol.Swift.GenericConstraint]>()
-    
+    public var constraintsVariants: DocumentationDataVariants<[SymbolGraph.Symbol.Swift.GenericConstraint]> {
+        var variants = DocumentationDataVariants<[SymbolGraph.Symbol.Swift.GenericConstraint]>()
+        for (trait, swiftExtension) in swiftExtensionVariants() {
+            variants[trait] = swiftExtension.constraints
+        }
+        return variants
+    }
+
     /// The inheritance information for the symbol in each language variant the symbol is available in.
     public var originVariants: DocumentationDataVariants<SymbolGraph.Relationship.SourceOrigin>
 
@@ -236,7 +248,6 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
         roleHeadingVariants: DocumentationDataVariants<String>,
         platformNameVariants: DocumentationDataVariants<PlatformName>,
         moduleReference: ResolvedTopicReference,
-        extendedModule: String? = nil,
         requiredVariants: DocumentationDataVariants<Bool> = .init(defaultVariantValue: false),
         externalIDVariants: DocumentationDataVariants<String>,
         accessLevelVariants: DocumentationDataVariants<String>,
@@ -292,8 +303,6 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
                     if !self.declarationVariants.hasVariant(for: trait) {
                         self.declarationVariants[trait] = [[platformNameVariants[trait]]: declaration]
                     }
-                case let extensionConstraints as SymbolGraph.Symbol.Swift.Extension where !extensionConstraints.constraints.isEmpty:
-                    self.constraintsVariants[trait] = extensionConstraints.constraints
                 case let location as SymbolGraph.Symbol.Location:
                     self.locationVariants[trait] = location
                 case let spi as SymbolGraph.Symbol.SPI:
@@ -323,12 +332,69 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
         self.redirectsVariants = redirectsVariants
         self.originVariants = originVariants
         self.automaticTaskGroupsVariants = automaticTaskGroupsVariants
-        self.extendedModule = extendedModule
     }
 
     public override func accept<V: SemanticVisitor>(_ visitor: inout V) -> V.Result {
         return visitor.visitSymbol(self)
     }
+
+    /// Append a new generic constraint for the given extended module
+    /// - Parameters:
+    ///    - extendedModule: The name of the extended module.
+    ///    - extendedSymbolKind: The kind of the extended symbol.
+    ///    - constraint: The new generic constraints to add.
+    public func addSwiftExtensionConstraint(
+        extendedModule: String,
+        extendedSymbolKind: SymbolGraph.Symbol.KindIdentifier? = nil,
+        constraint newConstraint: SymbolGraph.Symbol.Swift.GenericConstraint
+    ) {
+
+        var swiftExtension: SymbolGraph.Symbol.Swift.Extension
+
+        // Does this symbol already have a swift extension variant for the swift trait?
+
+        // Yes: Create a new copy of the existing extension with
+        // the new constraint appended to the existing list
+        let trait = DocumentationDataVariantsTrait.swift
+        if let existing = swiftExtensionVariants()[trait] {
+            // Double check the existing extension uses the same module and type. If it does not,
+            // we must have a tooling or data consistency problem.
+            assert(
+                existing.extendedModule == extendedModule && existing.typeKind == extendedSymbolKind,
+                "New constraint's module and type kind do not match symbol's existing constraints."
+            )
+            swiftExtension = existing
+            swiftExtension.constraints = swiftExtension.constraints + [newConstraint]
+
+        // No: Create a new extension with the specified module, type and
+        // new constraint
+        } else {
+            swiftExtension = SymbolGraph.Symbol.Swift.Extension(
+                                extendedModule: extendedModule,
+                                typeKind: extendedSymbolKind,
+                                constraints: [newConstraint]
+                             )
+        }
+
+        // Save the new or updated extension
+        self.mixinsVariants[
+                trait,
+                default: [:]
+            ][SymbolGraph.Symbol.Swift.Extension.mixinKey] = swiftExtension
+    }
+
+    // MARK: - Private helpers
+
+    /// Return all of this symbol's Swift extension variants.
+    private func swiftExtensionVariants() -> [DocumentationDataVariantsTrait : SymbolGraph.Symbol.Swift.Extension] {
+        var variants: [DocumentationDataVariantsTrait : SymbolGraph.Symbol.Swift.Extension] = [:]
+        for (trait, mixins) in mixinsVariants.allValues {
+            if let swiftExtension = mixins[SymbolGraph.Symbol.Swift.Extension.mixinKey] as? SymbolGraph.Symbol.Swift.Extension {
+                variants[trait] = swiftExtension
+            }
+        }
+        return variants
+    }
 }
 
 extension Symbol {
@@ -432,6 +498,10 @@ extension Symbol {
     /// The first variant of the symbol's platform, if available.
     public var platformName: PlatformName? { platformNameVariants.firstValue }
 
+    /// The first variant of the symbol's extended module, if available
+    @available(*, deprecated, message: "Please use extendedModuleVariants instead.")
+    public var extendedModule: String? { extendedModuleVariants.firstValue }
+
     /// Whether the first variant of the symbol is required in its context.
     public var isRequired: Bool {
         get { isRequiredVariants.firstValue! }
@@ -462,10 +532,7 @@ extension Symbol {
     }
 
     /// The first variant of the symbol's availability or conformance constraints.
-    public var constraints: [SymbolGraph.Symbol.Swift.GenericConstraint]? {
-        get { constraintsVariants.firstValue }
-        set { constraintsVariants.firstValue = newValue }
-    }
+    public var constraints: [SymbolGraph.Symbol.Swift.GenericConstraint]? { constraintsVariants.firstValue }
 
     /// The inheritance information for the first variant of the symbol.
     public var origin: SymbolGraph.Relationship.SourceOrigin? {