diff --git a/Sources/DocCHTML/CMakeLists.txt b/Sources/DocCHTML/CMakeLists.txt index 531ccff0b..6c15d451e 100644 --- a/Sources/DocCHTML/CMakeLists.txt +++ b/Sources/DocCHTML/CMakeLists.txt @@ -12,6 +12,7 @@ add_library(DocCHTML STATIC MarkdownRenderer+Availability.swift MarkdownRenderer+Breadcrumbs.swift MarkdownRenderer+Parameters.swift + MarkdownRenderer+Returns.swift MarkdownRenderer.swift WordBreak.swift XMLNode+element.swift) diff --git a/Sources/DocCHTML/MarkdownRenderer+Parameters.swift b/Sources/DocCHTML/MarkdownRenderer+Parameters.swift index 46e2ac32b..a316f6e49 100644 --- a/Sources/DocCHTML/MarkdownRenderer+Parameters.swift +++ b/Sources/DocCHTML/MarkdownRenderer+Parameters.swift @@ -34,9 +34,9 @@ package extension MarkdownRenderer { /// Creates a "parameters" section that describes all the parameters for a symbol. /// - /// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information. + /// If each language representation of the symbol has its own language-specific parameters, pass the parameter information for all language representations. /// - /// If the API has the _same_ parameters in all language representations, only pass the parameters for one language. + /// If all language representations of the symbol have the _same_ parameters, only pass the parameter information for one language. /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (same as if the symbol only had one language representation) func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> [XMLNode] { let info = RenderHelpers.sortedLanguageSpecificValues(info) diff --git a/Sources/DocCHTML/MarkdownRenderer+Returns.swift b/Sources/DocCHTML/MarkdownRenderer+Returns.swift new file mode 100644 index 000000000..f1599590d --- /dev/null +++ b/Sources/DocCHTML/MarkdownRenderer+Returns.swift @@ -0,0 +1,52 @@ +/* + This source file is part of the Swift.org open source project + + Copyright (c) 2025 Apple Inc. and the Swift project authors + Licensed under Apache License v2.0 with Runtime Library Exception + + See https://swift.org/LICENSE.txt for license information + See https://swift.org/CONTRIBUTORS.txt for Swift project authors +*/ + +#if canImport(FoundationXML) +// TODO: Consider other HTML rendering options as a future improvement (rdar://165755530) +package import FoundationXML +#else +package import Foundation +#endif + +package import Markdown +package import DocCCommon + +package extension MarkdownRenderer { + /// Creates a "returns" section that describes all return values of a symbol. + /// + /// If each language representation of the symbol has its own language-specific return values, pass the return value content for all language representations. + /// + /// If all language representations of the symbol have the _same_ return value, only pass the return value content for one language. + /// This produces a "returns" section that doesn't hide the return value content for any of the languages (same as if the symbol only had one language representation) + func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> [XMLNode] { + let info = RenderHelpers.sortedLanguageSpecificValues(languageSpecificSections) + let items: [XMLNode] = if info.count == 1 { + info.first!.value.map { visit($0) } + } else { + info.flatMap { language, content in + let attributes = ["class": "\(language.id)-only"] + // Most return sections only have 1 paragraph of content with 2 and 3 paragraphs being increasingly uncommon. + // Avoid wrapping that content in a `
First paragraph
+Second paragraph
+ """ + + switch goal { + case .richness: + returns.assertMatches(prettyFormatted: true, expectedXMLString: """ +First paragraph
+Second paragraph
+Other languageās paragraph
+ """ + + switch goal { + case .richness: + returns.assertMatches(prettyFormatted: true, expectedXMLString: """ +