-
Notifications
You must be signed in to change notification settings - Fork 129
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Support Possible Values section (#1006)
Support for Possible Values section. Support a new markdown tag, `possibleValues`, and a new `Possible Values` render section to document possible values extracted from the SymbolGraph. If a documented possible value does not correspond with the values from the SymbolGraph, it is dropped. rdar://123262314 - Links inside possible values description gets resolved. - Remove possible values from the Attributes render section. - Display all possible values in its own section. - Display possible values even when any is documented. - Made `Possible Values` public API.
- Loading branch information
1 parent
1b6e17b
commit a08f470
Showing
13 changed files
with
542 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
...s/SwiftDocC/Model/Rendering/RenderSectionTranslator/PossibleValuesSectionTranslator.swift
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| /* | ||
| This source file is part of the Swift.org open source project | ||
|
|
||
| Copyright (c) 2024 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 | ||
| */ | ||
|
|
||
| import Foundation | ||
| import SymbolKit | ||
| import Markdown | ||
|
|
||
| /// Translates a symbol's possible values into a render nodes's section. | ||
| struct PossibleValuesSectionTranslator: RenderSectionTranslator { | ||
|
|
||
| func translateSection(for symbol: Symbol, renderNode: inout RenderNode, renderNodeTranslator: inout RenderNodeTranslator) -> VariantCollection<CodableContentSection?>? { | ||
|
|
||
| return translateSectionToVariantCollection( | ||
| documentationDataVariants: symbol.possibleValuesSectionVariants | ||
| ) { _, possibleValuesSection in | ||
| // Render the possible values with the matching description from the | ||
| // possible values listed in the markdown. | ||
| return PossibleValuesRenderSection( | ||
| title: PropertyListPossibleValuesSection.title, | ||
| values: possibleValuesSection.possibleValues.map { possibleValueTag in | ||
| let valueContent = renderNodeTranslator.visitMarkupContainer( | ||
| MarkupContainer(possibleValueTag.contents) | ||
| ) as! [RenderBlockContent] | ||
| return PossibleValuesRenderSection.NamedValue( | ||
| name: possibleValueTag.value, | ||
| content: valueContent | ||
| ) | ||
| } | ||
| ) | ||
| } | ||
| } | ||
|
|
||
| } | ||
|
|
104 changes: 104 additions & 0 deletions
104
Sources/SwiftDocC/Model/Section/Sections/PropertyListPossibleValuesSection.swift
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| /* | ||
| This source file is part of the Swift.org open source project | ||
|
|
||
| Copyright (c) 2024 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 | ||
| */ | ||
|
|
||
| import Foundation | ||
| import Markdown | ||
| import SymbolKit | ||
|
|
||
| public struct PropertyListPossibleValuesSection { | ||
|
|
||
| /// A possible value. | ||
| /// | ||
| /// Documentation about a possible value of a symbol. | ||
| /// Write a possible value by prepending a line of prose with "- PossibleValue:" or "- PossibleValues:". | ||
| public struct PossibleValue { | ||
| /// The string representation of the value. | ||
| public var value: String | ||
| /// The content that describes the value. | ||
| public var contents: [Markup] | ||
| /// The text range where the parameter name was parsed. | ||
| var nameRange: SourceRange? | ||
| /// The text range where this parameter was parsed. | ||
| var range: SourceRange? | ||
|
|
||
| init(value: String, contents: [Markup], nameRange: SourceRange? = nil, range: SourceRange? = nil) { | ||
| self.value = value | ||
| self.contents = contents | ||
| self.nameRange = nameRange | ||
| self.range = range | ||
| } | ||
| } | ||
|
|
||
| public static var title: String { | ||
| return "Possible Values" | ||
| } | ||
|
|
||
| /// The list of possible values. | ||
| public let possibleValues: [PossibleValue] | ||
|
|
||
| struct Validator { | ||
| /// The engine that collects problems encountered while validating the possible values documentation. | ||
| var diagnosticEngine: DiagnosticEngine | ||
|
|
||
| /// Creates a new problem about documentation for a possible value that's not known to that symbol. | ||
| /// | ||
| /// ## Example | ||
| /// | ||
| /// ```swift | ||
| /// /// - PossibleValues: | ||
| /// /// - someValue: Some description of this value. | ||
| /// /// - anotherValue: Some description of a non-defined value. | ||
| /// /// ^~~~~~~~~~~~ | ||
| /// /// 'anotherValue' is not a known possible value for 'SymbolName'. | ||
| /// ``` | ||
| /// | ||
| /// - Parameters: | ||
| /// - unknownPossibleValue: The authored documentation for the unknown possible value name. | ||
| /// - knownPossibleValues: All known possible value names for that symbol. | ||
| /// - Returns: A new problem that suggests that the developer removes the documentation for the unknown possible value. | ||
| func makeExtraPossibleValueProblem(_ unknownPossibleValue: PossibleValue, knownPossibleValues: Set<String>, symbolName: String) -> Problem { | ||
|
|
||
| let source = unknownPossibleValue.range?.source | ||
| let summary = """ | ||
| \(unknownPossibleValue.value.singleQuoted) is not a known possible value for \(symbolName.singleQuoted). | ||
| """ | ||
| let identifier = "org.swift.docc.DocumentedPossibleValueNotFound" | ||
| let solutionSummary = """ | ||
| Remove \(unknownPossibleValue.value.singleQuoted) possible value documentation or replace it with a known value. | ||
| """ | ||
| let nearMisses = NearMiss.bestMatches(for: knownPossibleValues, against: unknownPossibleValue.value) | ||
|
|
||
| if nearMisses.isEmpty { | ||
| // If this possible value doesn't resemble any of this symbols possible values, suggest to remove it. | ||
| return Problem( | ||
| diagnostic: Diagnostic(source: source, severity: .warning, range: unknownPossibleValue.range, identifier: identifier, summary: summary), | ||
| possibleSolutions: [ | ||
| Solution( | ||
| summary: solutionSummary, | ||
| replacements: unknownPossibleValue.range.map { [Replacement(range: $0, replacement: "")] } ?? [] | ||
| ) | ||
| ] | ||
| ) | ||
| } | ||
| // Otherwise, suggest to replace the documented possible value name with the one of the similarly named possible values. | ||
| return Problem( | ||
| diagnostic: Diagnostic(source: source, severity: .warning, range: unknownPossibleValue.nameRange, identifier: identifier, summary: summary), | ||
| possibleSolutions: nearMisses.map { candidate in | ||
| Solution( | ||
| summary: "Replace \(unknownPossibleValue.value.singleQuoted) with \(candidate.singleQuoted)", | ||
| replacements: unknownPossibleValue.nameRange.map { [Replacement(range: $0, replacement: candidate)] } ?? [] | ||
| ) | ||
| } | ||
| ) | ||
| } | ||
| } | ||
|
|
||
| } | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.