Add DocC availability information to all directive pages #704
Conversation
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Layout/Column.md
Outdated
Show resolved
Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Layout/Small.md
Outdated
Show resolved
Hide resolved
rdar://110036742
d-ronnqvist
force-pushed
the
document-directive-availability
branch
from
78dd463
to
f1e2fef
Compare
|
Note that since this is a new protocol requirement it is a source breaking change for anyone who has defined their own directives. I could add a default value to mitigate this but my concern is that if new directives don't need to specify when they were introduced, we will forget to add it and the documentation will show the wrong version. |
| ), | ||
| SymbolGraph.Symbol.Availability.mixinKey: SymbolGraph.Symbol.Availability(availability: [ | ||
| .init( | ||
| domain: .init(rawValue: "Swift-DocC"), |
There was a problem hiding this comment.
Nice! Did you consider using "Swift" instead of "Swift-DocC" here? My mental model is that we don't actually have releases of Swift-DocC – Swift-DocC is just included in releases of Swift.
There was a problem hiding this comment.
I did consider it and I can change it if you prefer.
The only thing I wanted to avoid was someone misunderstanding "Swift 5.9+" and thinking that they can't use it because their package tools version is 5.8. It only matters what toolchain they have, but I'm not sure how to best convey that.
There was a problem hiding this comment.
Ah right. Great point. This reminds of a discussion on the forums I saw recently – we don't currently have a way to indicate "this API was introduced in Swift 5.9 but is back-ported to Swift 5.6 and so as long as you build with Swift 5.9, you can target version Swift 5.6 and use this symbol."
I think it makes since to use "Swift-DocC" at least until we solve that problem. Thanks!
|
@swift-ci please test |
| @@ -26,6 +26,7 @@ import Markdown | |||
| /// } | |||
| /// ``` | |||
| public final class DisplayName: Semantic, AutomaticDirectiveConvertible { | |||
| public static let introducedVersion = "5.6" | |||
There was a problem hiding this comment.
I'm having trouble confirming but I think this might have been 5.7?
There was a problem hiding this comment.
It looks like you're right. I was only looking at when each version was released but this doesn't seem to be on the 5.6 branch.
| @@ -28,6 +28,7 @@ import Markdown | |||
| /// } | |||
| /// ``` | |||
| public final class PageColor: Semantic, AutomaticDirectiveConvertible { | |||
| public static let introducedVersion = "5.8" | |||
There was a problem hiding this comment.
| public static let introducedVersion = "5.8" | |
| public static let introducedVersion = "5.9" |
|
@swift-ci please test |
Bug/issue #, if applicable: rdar://110036742
Summary
This add an
introducedVersionproperty toDirectiveConvertibleso that each directive page shows what version of DocC is the earliest version to support that directive.Dependencies
None
Testing
Run
swift run docc preview Sources/docc/DocCDocumentation.doccand inspect the various directive documentation pagesChecklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded