[SR-1161] Allow Cross-References in Documentation Markup

[swift-ci]

Previous ID	SR-1161
Radar	None
Original Reporter	deggert (JIRA User)
Type	Bug

Attachment: Download

Additional Detail from JIRA

| | | |------------------|-----------------| |Votes | 3 | |Component/s | Source Tooling | |Labels | Bug | |Assignee | None | |Priority | Medium | md5: 297043c1e3dc934f57f9c64897e8197c

Issue Description:

This renders, but Xcode doesn't link to the other one:

/// My Struct A
/// - SeeAlso: `B`
struct A {
}

/// My Struct B
/// - SeeAlso: `A`
struct B {
}

I'd expect the rendered documentation to have a link to the other struct.

[swift-ci]

Comment by Jason R Tibbetts (JIRA)

In Xcode 11, `- SeeAlso:` appears to be ignored completely in option-click popups. It doesn't even show up as part of the regular description; it's ignored completely.

    /// The description.
    ///
    /// # See also: AVPlayerController.load(playerItem:)
    /// - SeeAlso: This line doesn't appear
    /// - seeAlso: Neither does this one.
    /// - seealso: Case doesn't matter.
    open func load(playerItem: AVPlayerItem) {
        player?.load(playerItem: playerItem)
    }


[swift-ci]

Comment by Jason R Tibbetts (JIRA)

One workaround that StackOverflow suggests is to use a # Markdown header element, but headers can't include `code`, so that's suboptimal.