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]

Has the duplicates/overlap already been filtered out? Otherwise this could result in multiple variants with the same language.

[anferbui]

I think that's safe, see comment; only the first symbol reference will be respected by Swift-DocC Render and the rest will be ignored --WDYT?

[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.

[d-ronnqvist]

FYI: We have a .list(finalConjunction:) extension to BidirectionalCollection for this.

[d-ronnqvist]

Is there someplace that surfaces a user-facing diagnostic about this?

[d-ronnqvist]

This is unrealistic test data because a single symbol graph file contains symbols of different languages. Use different symbol graphs for each language just like the real data output from the respective compilers would be emitted.

[d-ronnqvist]

minor: There's no need to write the bundle to the file system just to read it back

Suggested change

	let tempURL = try createTempFolder(content: [exampleDocumentation])
	let (_, bundle, context) = try loadBundle(from: tempURL)
	let (bundle, context) = try loadBundle(catalog: exampleDocumentation)

[d-ronnqvist]

nit; the "Found problems" text almost looks like that output is expected. I had to read and the full test assertion and think about it to understand that it's unexpected. Also, if this test fails, the output of printing the full problem structures won't be that readable. Many other tests print the diagnostic summaries like this instead:

Suggested change

	XCTAssertTrue(problems.isEmpty, "Found problems: \(problems.joined(separator: ", "))")
	XCTAssertTrue(problems.isEmpty, "Unexpected problems: \(problems.map(\.diagnostic.summary).joined(separator: "\n"))")

[d-ronnqvist]

This is mixing user-facing terminology using "counterpart" instead of "alternate representation". We should aim to be consistent in everything that's user-facing.

[d-ronnqvist]

Question: what is this note about? Is this telling me that another directive in the same file already adds a representation with the same language? If so, maybe we could say "this" instead since the diagnostic would be associated with the right source location.

Suggested change

	An alternate representation for \(duplicateCounterpartLanguage.name) has already been defined by an @\(AlternateRepresentation.self) directive.
	This directive already specifies an alternate \(duplicateCounterpartLanguage.name) representation.

[d-ronnqvist]

Suggested change

	// Case where the original symbol already was defined in the languages of the counterpart symbol.
	// Check if the documented symbol already has alternate representations from in-source annotations.

[d-ronnqvist]

style: I'll just mention this once but I feel like forEach is just a worse and less capable version of a regular for loop and there's practically no use for it ever.

[d-ronnqvist]

style: I find this style to be a bit too much.

Suggested change

	problems
	.append(
	Problem(
	problems.append(Problem(