Skip to content

Add support for abstract Headerdoc tag #1215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 29, 2025
Merged

Add support for abstract Headerdoc tag #1215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b28f17e
Adding support for abstract headerdoc tag so the methods or propertie…
binamaniar May 8, 2025
e85bd7b
Merge branch 'main' into 147920933_abstract_headerdoc_tag
binamaniar May 26, 2025
92f9982
changes after merging swift markdown changes
binamaniar May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Package.resolved
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,10 @@ struct RenderContentCompiler: MarkupVisitor {
return renderableDirective.render(blockDirective, with: &self)
}

mutating func visitDoxygenAbstract(_ doxygenAbstract: DoxygenAbstract) -> [any RenderContent] {
doxygenAbstract.children.flatMap { self.visit($0)}
}

mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) -> [any RenderContent] {
doxygenDiscussion.children.flatMap { self.visit($0) }
}
Expand Down
6 changes: 4 additions & 2 deletions Tests/SwiftDocCTests/Semantics/DoxygenTests.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ class DoxygenTests: XCTestCase {
func testDoxygenDiscussionAndNote() throws {
let documentationLines: [SymbolGraph.LineList.Line] = """
This is an abstract.
@abstract This is description with abstract.

@discussion This is a discussion linking to ``AnotherClass`` and ``AnotherClass/prop``.

Expand Down Expand Up @@ -96,6 +97,7 @@ class DoxygenTests: XCTestCase {

XCTAssertEqual(symbol.abstract?.format(), "This is an abstract.")
XCTAssertEqual(symbol.discussion?.content.map { $0.format() }, [
#"\abstract This is description with abstract."#,
#"\discussion This is a discussion linking to ``doc://unit-test/documentation/ModuleName/AnotherClass`` and ``doc://unit-test/documentation/ModuleName/AnotherClass/prop``."#,
Comment on lines +100 to 101
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would happen if these two lines were flipped? If the "abstract" content becomes the second sentence in the discussion section, then I'd argue that it's more important that we actually parse @abstract as an abstract (like Vera pointed our here).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be a confusing workflow to support in terms of how the abstract is written while documenting, where the first time without tag is abstract, followed by discussion tag, and if there is a abstract tag post that, we would need to append to the abstract in the first line. It is an interesting scenario to think about but I don't know for sure we should support/facilitate that workflow.

#"\note This is a note linking to ``doc://unit-test/documentation/ModuleName/Class3`` and ``Class3/prop2``."#
])
Expand All @@ -108,10 +110,10 @@ class DoxygenTests: XCTestCase {
XCTAssertEqual(renderNode.primaryContentSections.count, 1)

let overviewSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
XCTAssertEqual(overviewSection.content.count, 3)
XCTAssertEqual(overviewSection.content.count, 4)
XCTAssertEqual(overviewSection.content, [
.heading(.init(level: 2, text: "Overview", anchor: "overview")),

.paragraph(.init(inlineContent: [.text("This is description with abstract.")])),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we try to actually parse @abstract as an abstract? I feel like it would stay true to the use of the command.

On the other hand, we probably shouldn't add too much Doxygen/HeaderDoc support, since we really want to push people to using Markdown... 😅 I'm fine either way on this, though i'm curious what the workgroup (or just the rest of our team) thinks.

Copy link
Contributor Author

@binamaniar binamaniar May 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the thought of having limited Oxygen/HeaderDoc support I thought we should not restrain from parsing @abstract as an abstract. But open to other ideas too and can be convinced otherwise :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like we should at least explore what it would take for @abstract to become the abstract instead of being a sentence in the discussion.

It might also be good to verify that links in the abstract are resolved. IIRC this doesn't happen automatically for new elements.

.paragraph(.init(inlineContent: [
.text("This is a discussion linking to "),
.reference(
Expand Down