From b28f17e1e1c946ab6457f2a18cb4d77fcc4945fe Mon Sep 17 00:00:00 2001 From: Bina Maniar Date: Thu, 8 May 2025 16:04:06 -0700 Subject: [PATCH 1/2] Adding support for abstract headerdoc tag so the methods or properties with abstract headerdoc tag retains documentation --- Package.resolved | 40 +++++++++---------- Package.swift | 2 +- .../Rendering/RenderContentCompiler.swift | 4 ++ .../Semantics/DoxygenTests.swift | 6 ++- 4 files changed, 29 insertions(+), 23 deletions(-) diff --git a/Package.resolved b/Package.resolved index 3e7b804f6e..a22d0e021f 100644 --- a/Package.resolved +++ b/Package.resolved @@ -5,8 +5,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-argument-parser.git", "state" : { - "revision" : "0fbc8848e389af3bb55c182bc19ca9d5dc2f255b", - "version" : "1.4.0" + "revision" : "41982a3656a71c768319979febd796c6fd111d5c", + "version" : "1.5.0" } }, { @@ -14,8 +14,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-asn1.git", "state" : { - "revision" : "7faebca1ea4f9aaf0cda1cef7c43aecd2311ddf6", - "version" : "1.3.0" + "revision" : "a54383ada6cecde007d374f58f864e29370ba5c3", + "version" : "1.3.2" } }, { @@ -33,7 +33,7 @@ "location" : "https://github.com/swiftlang/swift-cmark.git", "state" : { "branch" : "gfm", - "revision" : "2c47322cb32cbed555f13bf5cbfaa488cc30a785" + "revision" : "b97d09472e847a416629f026eceae0e2afcfad65" } }, { @@ -41,8 +41,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-collections.git", "state" : { - "revision" : "3d2dc41a01f9e49d84f0a3925fb858bed64f702d", - "version" : "1.1.2" + "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7", + "version" : "1.1.4" } }, { @@ -50,8 +50,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-crypto.git", "state" : { - "revision" : "06dc63c6d8da54ee11ceb268cde1fa68161afc96", - "version" : "3.9.1" + "revision" : "e8d6eba1fef23ae5b359c46b03f7d94be2f41fed", + "version" : "3.12.3" } }, { @@ -59,8 +59,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/swiftlang/swift-docc-plugin.git", "state" : { - "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247", - "version" : "1.3.0" + "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64", + "version" : "1.4.3" } }, { @@ -69,7 +69,7 @@ "location" : "https://github.com/swiftlang/swift-docc-symbolkit.git", "state" : { "branch" : "main", - "revision" : "96bce1cfad4f4d7e265c1eb46729ebf8a7695f4b" + "revision" : "ddacb655e2087fd722cb5ca2bcc49953ee267e37" } }, { @@ -78,16 +78,16 @@ "location" : "https://github.com/swiftlang/swift-lmdb.git", "state" : { "branch" : "main", - "revision" : "c42582487fe84f72a4d417dd2d8493757bd4d072" + "revision" : "1ad9a2d80b6fcde498c2242f509bd1be7d667ff8" } }, { "identity" : "swift-markdown", "kind" : "remoteSourceControl", - "location" : "https://github.com/swiftlang/swift-markdown.git", + "location" : "https://github.com/binamaniar/swift-markdown.git", "state" : { - "branch" : "main", - "revision" : "d21714073e0d16ba78eebdf36724863afc36871d" + "branch" : "support_abstract_headerdoc", + "revision" : "3d4d4196d9e1f3acc216755c542e71430f752984" } }, { @@ -95,8 +95,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio.git", "state" : { - "revision" : "fc79798d5a150d61361a27ce0c51169b889e23de", - "version" : "2.68.0" + "revision" : "0f54d58bb5db9e064f332e8524150de379d1e51c", + "version" : "2.82.1" } }, { @@ -104,8 +104,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-system.git", "state" : { - "revision" : "6a9e38e7bd22a3b8ba80bddf395623cf68f57807", - "version" : "1.3.1" + "revision" : "a34201439c74b53f0fd71ef11741af7e7caf01e1", + "version" : "1.4.2" } } ], diff --git a/Package.swift b/Package.swift index 2381b5dfeb..1df227acbe 100644 --- a/Package.swift +++ b/Package.swift @@ -134,7 +134,7 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil { // Building standalone, so fetch all dependencies remotely. package.dependencies += [ .package(url: "https://github.com/apple/swift-nio.git", from: "2.53.0"), - .package(url: "https://github.com/swiftlang/swift-markdown.git", branch: "main"), + .package(url: "https://github.com/binamaniar/swift-markdown.git", branch: "support_abstract_headerdoc"), .package(url: "https://github.com/swiftlang/swift-lmdb.git", branch: "main"), .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2"), .package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", branch: "main"), diff --git a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift index a8c03b5c26..58fabccede 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift @@ -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) } } diff --git a/Tests/SwiftDocCTests/Semantics/DoxygenTests.swift b/Tests/SwiftDocCTests/Semantics/DoxygenTests.swift index 664ce47513..99b7d85950 100644 --- a/Tests/SwiftDocCTests/Semantics/DoxygenTests.swift +++ b/Tests/SwiftDocCTests/Semantics/DoxygenTests.swift @@ -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``. @@ -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``."#, #"\note This is a note linking to ``doc://unit-test/documentation/ModuleName/Class3`` and ``Class3/prop2``."# ]) @@ -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.")])), .paragraph(.init(inlineContent: [ .text("This is a discussion linking to "), .reference( From 92f99825442eee27bf63eef551b06c49f30cefd8 Mon Sep 17 00:00:00 2001 From: Bina Maniar Date: Wed, 28 May 2025 17:18:38 -0700 Subject: [PATCH 2/2] changes after merging swift markdown changes --- Package.resolved | 40 ++++++++++++++++++++-------------------- Package.swift | 2 +- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/Package.resolved b/Package.resolved index a22d0e021f..9e5da617d2 100644 --- a/Package.resolved +++ b/Package.resolved @@ -5,8 +5,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-argument-parser.git", "state" : { - "revision" : "41982a3656a71c768319979febd796c6fd111d5c", - "version" : "1.5.0" + "revision" : "0fbc8848e389af3bb55c182bc19ca9d5dc2f255b", + "version" : "1.4.0" } }, { @@ -14,8 +14,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-asn1.git", "state" : { - "revision" : "a54383ada6cecde007d374f58f864e29370ba5c3", - "version" : "1.3.2" + "revision" : "7faebca1ea4f9aaf0cda1cef7c43aecd2311ddf6", + "version" : "1.3.0" } }, { @@ -33,7 +33,7 @@ "location" : "https://github.com/swiftlang/swift-cmark.git", "state" : { "branch" : "gfm", - "revision" : "b97d09472e847a416629f026eceae0e2afcfad65" + "revision" : "2c47322cb32cbed555f13bf5cbfaa488cc30a785" } }, { @@ -41,8 +41,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-collections.git", "state" : { - "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7", - "version" : "1.1.4" + "revision" : "3d2dc41a01f9e49d84f0a3925fb858bed64f702d", + "version" : "1.1.2" } }, { @@ -50,8 +50,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-crypto.git", "state" : { - "revision" : "e8d6eba1fef23ae5b359c46b03f7d94be2f41fed", - "version" : "3.12.3" + "revision" : "06dc63c6d8da54ee11ceb268cde1fa68161afc96", + "version" : "3.9.1" } }, { @@ -59,8 +59,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/swiftlang/swift-docc-plugin.git", "state" : { - "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64", - "version" : "1.4.3" + "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247", + "version" : "1.3.0" } }, { @@ -69,7 +69,7 @@ "location" : "https://github.com/swiftlang/swift-docc-symbolkit.git", "state" : { "branch" : "main", - "revision" : "ddacb655e2087fd722cb5ca2bcc49953ee267e37" + "revision" : "96bce1cfad4f4d7e265c1eb46729ebf8a7695f4b" } }, { @@ -78,16 +78,16 @@ "location" : "https://github.com/swiftlang/swift-lmdb.git", "state" : { "branch" : "main", - "revision" : "1ad9a2d80b6fcde498c2242f509bd1be7d667ff8" + "revision" : "c42582487fe84f72a4d417dd2d8493757bd4d072" } }, { "identity" : "swift-markdown", "kind" : "remoteSourceControl", - "location" : "https://github.com/binamaniar/swift-markdown.git", + "location" : "https://github.com/swiftlang/swift-markdown.git", "state" : { - "branch" : "support_abstract_headerdoc", - "revision" : "3d4d4196d9e1f3acc216755c542e71430f752984" + "branch" : "main", + "revision" : "5ad49ed3219261b085e86da832d0657752bba63c" } }, { @@ -95,8 +95,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio.git", "state" : { - "revision" : "0f54d58bb5db9e064f332e8524150de379d1e51c", - "version" : "2.82.1" + "revision" : "fc79798d5a150d61361a27ce0c51169b889e23de", + "version" : "2.68.0" } }, { @@ -104,8 +104,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-system.git", "state" : { - "revision" : "a34201439c74b53f0fd71ef11741af7e7caf01e1", - "version" : "1.4.2" + "revision" : "6a9e38e7bd22a3b8ba80bddf395623cf68f57807", + "version" : "1.3.1" } } ], diff --git a/Package.swift b/Package.swift index 1df227acbe..2381b5dfeb 100644 --- a/Package.swift +++ b/Package.swift @@ -134,7 +134,7 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil { // Building standalone, so fetch all dependencies remotely. package.dependencies += [ .package(url: "https://github.com/apple/swift-nio.git", from: "2.53.0"), - .package(url: "https://github.com/binamaniar/swift-markdown.git", branch: "support_abstract_headerdoc"), + .package(url: "https://github.com/swiftlang/swift-markdown.git", branch: "main"), .package(url: "https://github.com/swiftlang/swift-lmdb.git", branch: "main"), .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2"), .package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", branch: "main"),