Add support for transforming Doxygen discussion/note tags

[j-f1]

Bug/issue #, if applicable: Related to rdar://116077012

Summary

This note adds support for formatting Doxygen @discussion and @note tags. Discussion tags are turned into normal paragraphs, while @note tags are turned into “note” blocks.

Dependencies

• Add support for Doxygen discussion/note tags swift-markdown#159
• Add support for formatting the new Doxygen types using MarkupFormatter swift-markdown#163

Testing

Create a documentation comment containing @note or @discussion tags:

This is an overview.

@discussion This is a discussion.

@note Please take note.

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 — I don’t think this is needed, right?

[j-f1]

@swift-ci please test

[d-ronnqvist]

Does the reference resolver already visit this content? A good way to check would be to add unresolvable links in both places and look for warnings:

This is an overview.

@discussion This is a <doc:NotFound> discussion.

@note Please take <doc:NotFound> note.

[j-f1]

Does the reference resolver already visit this content? A good way to check would be to add unresolvable links in both places and look for warnings:

Added that doc comment to a test project and got warnings on both links.

[j-f1]

@swift-ci please test

[j-f1]

@swift-ci please test

[d-ronnqvist]

Thanks for opening this PR.

Can you add some tests that verify:

• that the content of these tags is available on the in-memory node
• that these tags renders as expected
• that links in content within these tags get resolved

Something like this should be able to serve as a starting point for a test.

func testDoxygenDiscussionAndNote() throws {
    let documentationLines: [SymbolGraph.LineList.Line] = """
        This is an abstract.

        @discussion This is a discussion.

        @note This is a note.
        """
        .splitByNewlines
        .enumerated()
        .map { index, line in
            SymbolGraph.LineList.Line(
                text: line,
                range: .init(start: .init(line: 1 + index, character: 1), end: .init(line: 1 + index, character: 1 + line.utf8.count))
            )
        }
    
    let tempURL = try createTempFolder(content: [
        Folder(name: "unit-test.docc", content: [
            JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
                moduleName: "ModuleName",
                symbols: [
                    SymbolGraph.Symbol(
                        identifier: .init(precise: "some-class-id", interfaceLanguage: SourceLanguage.swift.id),
                        names: .init(title: "SomeClass", navigator: nil, subHeading: nil, prose: nil),
                        pathComponents: ["SomeClass"],
                        docComment: .init(documentationLines),
                        accessLevel: .public,
                        kind: .init(parsedIdentifier: .class, displayName: "Kind Display Name"),
                        mixins: [:]
                    )
                ]
            )),
        ])
    ])
    
    let (_, bundle, context) = try loadBundle(from: tempURL)
    let reference = ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/documentation/ModuleName/SomeClass", sourceLanguage: .swift)
    
    // Verify the expected content in the in-memory model
    let node = try context.entity(with: reference)
    let symbol = try XCTUnwrap(node.semantic as? Symbol)
    
    XCTAssertEqual(symbol.abstract?.format(), "This is an abstract.")
    XCTAssertEqual(symbol.discussion?.content.map { $0.format() }, ["This is a discussion.", "This is a note."])
    
    // Verify the expected content in the render model
    var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: node.reference, source: nil)
    let renderNode = try XCTUnwrap(translator.visit(node.semantic) as? RenderNode)
    
    XCTAssertEqual(renderNode.abstract, [.text("This is an abstract.")])
    XCTAssertEqual(renderNode.primaryContentSections.count, 1)
    
    let overviewSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
    XCTAssertEqual(overviewSection.content.count, 3)
    
    XCTAssertEqual(overviewSection.content, [
        .heading(.init(level: 2, text: "Overview", anchor: "overview")),
        
        .paragraph(.init(inlineContent: [
            .text("This is a discussion.")
        ])),
        
        .aside(.init(style: .init(asideKind: .note), content: [
            .paragraph(.init(inlineContent: [
                .text("This is a note.")
            ]))
        ])),
    ])
}

Note that it's just a starting point. It is incomplete in that it doesn't really verify the content of the in-memory node and that it doesn't include any links in the content.

[j-f1]

What do you mean by “verify the content of the in-memory node?” Does that mean I should be introspecting symbol.discussion?.content and not just comparing the formatted strings in the test? Added your test + some links in the meantime.

[j-f1]

@swift-ci please test

[j-f1]

@swift-ci please testr

[d-ronnqvist]

This looks good to me.

I wonder if needing to explicitly handle DoxygenDiscussion and DoxygenNote when working with the in-memory models could be something that developer forgets and that new features won't automatically be supported in such content but at the moment I don't know of a better way to handle the in-memory models, and that's always a change we can make in the future—for example if we find this to be a problem.

[j-f1]

@swift-ci please test