Collect external links from various symbol section types (#855)

* Collect external links from _symbol_ deprecation summary content

rdar://120374614

* ExternalReferenceWalker#visitSymbol visits all types of Symbol sections
that might contain external links.

Also, ReferenceResolver#visitSymbol visits HTTPBodyParameters.

* ExternalReferenceWalker visits all variants of symbols. Refactor unit
tests to use realistic symbol graph files for HTTP/REST API symbols.

---------

Co-authored-by: David Rönnqvist <[email protected]>

Author: patshaughnessy

Sources/SwiftDocC/Semantics/ExternalLinks/ExternalReferenceWalker.swift

@@ -174,22 +174,58 @@ struct ExternalReferenceWalker: SemanticVisitor {
     }
 
     mutating func visitComment(_ comment: Comment) { }
-    
+
+    mutating func visitSection(_ section: Section) {
+        for markup in section.content { visitMarkup(markup) }
+    }
+
+    mutating func visitSectionVariants(_ variants: DocumentationDataVariants<some Section>) {
+        for variant in variants.allValues.map(\.variant) {
+            visitSection(variant)
+        }
+    }
+
     mutating func visitSymbol(_ symbol: Symbol) {
-        symbol.abstractSection.unwrap { visitMarkup($0.paragraph) }
-        symbol.discussion.unwrap { $0.content.forEach { visitMarkup($0) }}
-        symbol.topics.unwrap { $0.content.forEach { visitMarkup($0) }}
-        symbol.seeAlso.unwrap { $0.content.forEach { visitMarkup($0) }}
-        symbol.returnsSection.unwrap { $0.content.forEach { visitMarkup($0) }}
-        symbol.deprecatedSummary.unwrap { $0.content.forEach { visitMarkup($0) }}
-        
-        symbol.parametersSection.unwrap {
-            $0.parameters.forEach {
-                $0.contents.forEach { visitMarkup($0) }
+
+        visitSectionVariants(symbol.abstractSectionVariants)
+        visitSectionVariants(symbol.discussionVariants)
+        visitSectionVariants(symbol.topicsVariants)
+        visitSectionVariants(symbol.seeAlsoVariants)
+        visitSectionVariants(symbol.returnsSectionVariants)
+        visitSectionVariants(symbol.deprecatedSummaryVariants)
+
+        if let parametersSection = symbol.parametersSection {
+            for parameter in parametersSection.parameters {
+                for markup in parameter.contents { visitMarkup(markup) }
+            }
+        }
+
+        for dictionaryKeysSection in symbol.dictionaryKeysSectionVariants.allValues.map(\.variant) {
+            for dictionaryKeys in dictionaryKeysSection.dictionaryKeys {
+                for markup in dictionaryKeys.contents { visitMarkup(markup) }
+            }
+        }
+
+        for httpParametersSection in symbol.httpParametersSectionVariants.allValues.map(\.variant) {
+            for param in httpParametersSection.parameters {
+                for markup in param.contents { visitMarkup(markup) }
+            }
+        }
+
+        for httpResponsesSection in symbol.httpResponsesSectionVariants.allValues.map(\.variant) {
+            for param in httpResponsesSection.responses {
+                for markup in param.contents { visitMarkup(markup) }
+            }
+        }
+
+        for httpBodySection in symbol.httpBodySectionVariants.allValues.map(\.variant) {
+            for markup in httpBodySection.body.contents { visitMarkup(markup) }
+            for parameter in httpBodySection.body.parameters {
+                for markup in parameter.contents { visitMarkup(markup) }
             }
         }
     }
-    
+
     mutating func visitDeprecationSummary(_ summary: DeprecationSummary) {
         visit(summary.content)
     }

Sources/SwiftDocC/Semantics/ReferenceResolver.swift

@@ -456,7 +456,10 @@ struct ReferenceResolver: SemanticVisitor {
         }
         let newHTTPBodyVariants = symbol.httpBodySectionVariants.map { httpBodySection -> HTTPBodySection in
             let oldBody = httpBodySection.body
-            let newBody = HTTPBody(mediaType: oldBody.mediaType, contents: oldBody.contents.map { visitMarkup($0) }, parameters: oldBody.parameters, symbol: oldBody.symbol)
+            let newBodyParameters = oldBody.parameters.map {
+                HTTPParameter(name: $0.name, source: $0.source, contents: $0.contents.map { visitMarkup($0) }, symbol: $0.symbol, required: $0.required)
+            }
+            let newBody = HTTPBody(mediaType: oldBody.mediaType, contents: oldBody.contents.map { visitMarkup($0) }, parameters: newBodyParameters, symbol: oldBody.symbol)
             return HTTPBodySection(body: newBody)
         }
         let newHTTPParametersVariants = symbol.httpParametersSectionVariants.map { httpParametersSection -> HTTPParametersSection in

Sources/SwiftDocC/Semantics/Symbol/Symbol.swift

@@ -536,6 +536,10 @@ extension [String: Mixin] {
 
 // MARK: Accessors for the first variant of symbol properties.
 
+// Extend the Symbol class to account for legacy code that didn't account for symbols having multiple
+// language representations. New code should be written to work with the variants so that it supports
+// language specific content.
+
 extension Symbol {
     /// The kind of the first variant of this symbol, such as protocol or variable.
     public var kind: SymbolGraph.Symbol.Kind { kindVariants.firstValue! }
@@ -686,10 +690,12 @@ extension Symbol {
         get { mixinsVariants.firstValue }
         set { mixinsVariants.firstValue = newValue }
     }
-    
+
     /// Any automatically created task groups of the first variant of the symbol.
     var automaticTaskGroups: [AutomaticTaskGroupSection] {
         get { automaticTaskGroupsVariants.firstValue! }
         set { automaticTaskGroupsVariants.firstValue = newValue }
     }
+
+    // Don't add additional functions here. See the comment above about legacy code.
 }