Add directive for linking symbols as alternate representations

[anferbui]

Bug/issue #, if applicable: rdar://109417745

Summary

Adds a directive which is meant to be used in markdown extension files for a specific symbol:

@Metadata {
  @AlternateRepresentation(``MyApp/MyClass/property``)
}

Where all variants of MyApp/MyClass/property will be added as variants of the current symbol.

Its purpose is to be able to define an alternative language representation for a symbol, where the alternative symbol is an unrelated symbol as far as the compiler is aware (i.e. they have different USRs in the symbol graph).

This makes it possible to switch between both symbols through the language switcher:

Whenever possible, the alternative language representations should be defined in-source, by using in-source annotations such as the @objc and @_objcImplementation attributes in Swift, or the NS_SWIFT_NAME macro in Objective C.

However, if this is not possible, this is an alternative to be able to render both symbols as counterparts of each other.

Diagnostics

Links within the directive are resolved, and emit a warning if the link cannot be resolved same as all other markup links:

    warning: 'MissingSymbol' doesn't exist at '/Synonyms'
     --> SynonymSample.docc/SymbolExtension2.md:4:19-4:32
    2 |
    3 | @Metadata {
    4 +     @AlternateRepresentation(``Synonyms/MissingSymbol``)
    5 | }

Duplication of source language availability is also detected:

• if the symbol the alternate representation is being defined for (the "original" symbol) was already available in one of the languages the counterpart symbol is available in
• if the alternate representations have duplicate source languages in common, i.e. if counterpart1 is available in Objective-C and counterpart2 is also available in Objective-C.

And suggestions will be provided depending on context:

• which languages are duplicate
• all the languages the symbol is already available in will be available as part of the diagnostic explanation
• if the @AlternateRepresentation directive is a duplicate, a suggestion will be made to remove it, with a suitable replacement
• if the @AlternateRepresentation directive is a duplicate, a note pointing to the original directive will be added

warning: An alternate representation for Swift already exists
This node is already available in Swift and Objective-C.
SynonymSample.docc/SymbolExtension2.md:4:5: An alternate representation for Swift has already be
en defined by an @AlternateRepresentation directive.
--> SynonymSample.docc/SymbolExtension2.md:5:5-5:57
3 | @Metadata {
4 |     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
5 +     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
 |     ╰─suggestion: Remove this alternate representation
6 | }
7 |

warning: This node already has a representation in Swift
This node is already available in Swift.
 --> SynonymSample.docc/SynonymExtension.md:5:5-5:56
3 | @Metadata {
4 |     @AlternateRepresentation(``Synonyms/Synonym-1wqxt``)
5 +     @AlternateRepresentation(``Synonyms/OtherSynonym``)
  |     ╰─suggestion: Replace the counterpart link with a node which isn't available in Swift
6 | }
7 |

Dependencies

None.

Testing

Tested by building and rendering the following archive locally, which uses the new directive:
SynonymSample.docc.zip

This contains two symbols which have been configured to be counterparts of each other.

You should be able to switch between both symbols using the language picker from either:
http://localhost:8080/documentation/synonyms/synonym-1wqxt?language=objc
or
http://localhost:8080/documentation/synonyms/synonym-5zxmc

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[d-ronnqvist]

Before I get into the code, some feedback on this syntax:

@Metadata {
  @Synonym(language: swift) {
     ``MyApp/MyClass/property``
  }
}

• It would be structurally simpler if the link was a parameter instead of inner content. That would also simplify the implementation by not needing to validate the type of inner content.

• I'm not too happy about the phrase "synonym" for this. In technical terms I tend to refer to this concept as a "counterpart" or as an "alternate representation".

• I wonder if the language parameter is really needed. DocC should know the available languages of the current symbol and—assuming the link resolves—the available languages of the authored counterpart symbol. Assuming that neither symbol already has counterparts, DocC should be able to infer the source language from the resolves counterpart symbol. If on the other hand either symbol already has representations in multiple languages, it raises some interesting questions regarding what this directive should do. For example; should it be possible to author a different Swift representation/counterpart for a symbol that already has a Swift representation/counterpart?

[d-ronnqvist]

If this is the only place that checks that the link resolved we should emit a warning with the right link source range so that the developer knows that the link failed to resolve.

unresolvedReferenceProblem(...) can create the same type of diagnostic as for other unresolved links by passing the TopicReferenceResolutionErrorInfo from the TopicReferenceResolutionResult.failure(_:_:).

[anferbui]

We will already emit a diagnostic in the code below so I don't think it's also needed here, WDYT?

swift-docc/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

Lines 614 to 621 in bc6df51

	// Also resolve the node's alternate declaration. This isn't part of the node's 'semantic' value (resolved above).
	documentationNode.metadata?.alternateDeclarations.forEach { synonym in
	resolver.resolve(
	synonym: synonym,
	range: synonym.originalMarkup.range,
	severity: .warning
	)
	}

Since this ultimately ends up adding this diagnostic:

swift-docc/Sources/SwiftDocC/Semantics/ReferenceResolver.swift

Line 117 in bc6df51

problems.append(unresolvedReferenceProblem(source: range?.source, range: range, severity: severity, uncuratedArticleMatch: uncuratedArticleMatch, errorInfo: error, fromSymbolLink: false))

(I can add a comment to explain why we don't need a diagnostic here)

[anferbui]

@swift-ci Please test

[d-ronnqvist]

The implementation generally looks good but the tests are unrealistic and don't cover a handful of behaviors that should raise diagnostics. Also, I think much of the user-facing documentation and other user-facing text could benefit from some refinements.

[anferbui]

@swift-ci please test

[d-ronnqvist]

The code looks good but I'd like to make one more iteration on the user facing documentation.

[d-ronnqvist]

minor: I don't think this function is helping the readability of the rest of this code.

---

The first usage could be written as one these alternatives without the mapSourceLanguageToVariants function

var allVariants: [SourceLanguage: ResolvedTopicReference] = documentationNode.availableSourceLanguages.reduce(into: [:]) { partialResult, language in
    partialResult[language] = identifier
}

var allVariants = [SourceLanguage: ResolvedTopicReference]()
for language in documentationNode.availableSourceLanguages {
    allVariants[language] = identifier
}

I find both alternatives to be more explicit in how the data is being built up.

---

Similarly, the second usage could be written s one these alternatives without the mapSourceLanguageToVariants function

for language in alternateRepresentationReference.sourceLanguages.subtracting(allVariants.keys) {
    allVariants[language] = alternateRepresentationReference
}

allVariants.merge(
    alternateRepresentationReference.sourceLanguages.map { ($0, alternateRepresentationReference) }
) { existing, _ in existing }

---

Also, I don't see the reason to store an array of references for each language when the only value ever is a single element, so in the examples above I used [SourceLanguage: ResolvedTopicReference] instead of [SourceLanguage: [ResolvedTopicReference]].

The only difference that I can see is that the creation of the RenderNode.Variant towards the end would create the array inline from the only reference

  RenderNode.Variant(
      traits: [.interfaceLanguage(sourceLanguage.id)],
+     paths: [
-     paths: references.map { reference in
          generator.presentationURLForReference(reference).path
-     }
+     ]
  )

[anferbui]

Seems reasonable to me, I agree it makes it clearer to use a ResolvedTopicReference over a [ResolvedTopicReference] to emphasise there can only be one. The main reason I wasn't doing that originally is to remove the chances of unintentionally causing a regression in behaviour.

Previously, we weren't enforcing having only one path per trait, so even though I can't think of a case where there would have been multiple paths per trait, it could have theoretically happened. I'm not sure if enforcing it will have unintentional consequences, but I think it does make it clearer to enforce it here.

Made the suggested changes, thanks for the code suggestions!

[anferbui]

@swift-ci please test

[d-ronnqvist]

Thanks for all the iterations.
This looks good to me.

[anferbui]

@swift-ci please test