Documentation Workgroup meeting: June 3rd, 2024

The Documentation Workgroup will be holding its next meeting on Monday, June 3rd, 2024 from 8:30am to 9:30am PT (or see the time in your own timezone).

This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.

Meeting notes for this meeting will posted in this thread shortly after.

Agenda

Please propose any additional agenda items in this thread.

1 Like

i’d like to add an additional item about inconsistency between behavior of swift build -emit-symbol-graph and swift symbolgraph-extract with respect to @_exported declarations

1 Like

I'd like to provide some more background for the discussion here, as well as some specific recommendations.

Right now, when an API or module has availability information, DocC shows the platform availability as a set of "pills" showing platform and version. For example, here's what we show for the SwiftSyntax module on the package index:

While this information is not wrong, it is incomplete and therefore gives the wrong impression. This package and module work on every platform Swift supports, but it looks like it is only available on Apple platforms. We've received feedback about this being confusing for developers who don't know if a given Swift package works on Linux or Windows.

Swift's availability syntax was intentionally designed with an explicit * to indicate that something is assumed available on every platform that isn't explicitly mentioned. So an API expressed like this:

@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public func f() { }

is available on all platforms. On macOS, you need macOS 10.15. On iOS, you need iOS 13.0, etc.

I think DocC needs the equivalent of the * to clarify that code works on all platforms. This is achievable on the module level by adding a custom entry to the CDAppleDefaultAvailability array in the Info.plist, e.g.,

<dict>
        <key>name</key>
        <string>All Swift Platforms</string>
        <key>version</key>
        <string>5.1</string>
</dict>

Recommendation #1: we come up with a canonical spelling and version to represent "everywhere that Swift works." Here, I've used "All Swift Platforms" and the minimum supported Swift version (in this case 5.1).

Once we have an agreed-upon spelling, we should find a way to get this change to ripple through the package ecosystem. We have a few tools at our disposal to do this, in order of increasing aggressiveness:

  1. We can document that this is best practice and socialize it
  2. We can have DocC warn when there are CDAppleDefaultAvailability entries but none for "All Swift Platforms"
  3. We can have DocC infer an "All Swift Platforms" entry if none was provided. The only hard part here is inferring a version number. It's possible to map backwards from (say) iOS or macOS version numbers of the corresponding Swift runtime version.

Doing (2) and (3) probably require some opt-out mechanism to silence the warning / inference by adding another entry somewhere in the Info.plist.

Recommendation #2: pick one of the more aggressive tools to get "All Swift Platforms" to ripple through the ecosystem quickly. (2) effectively matches what the compiler does with availability, so that one is easy.

Recommendation #3: We should rename the CDAppleDefaultAvailability key to CDDefaultAvailability. Availability is not an Apple-only concept, even though we currently only define ABI stability on Apple platforms.

As a bonus topic, there's another semi-platform coming up that could similarly benefit from having a standardized spelling for availability: Embedded Swift. It does take work to get a package to build with Embedded Swift, so it needs to be opt in.

Recommendation #4: Standardize on "Embedded" as the platform name for a library that supports Embedded Swift, where the version is the minimum Swift version.

Doug

7 Likes

The @Available attribute also supports Swift (@Available(swift, 5.0)):

@available(swift, 5.0)
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public func f() { }

This info is added to the API documentation like any other platform, and, IMO this conveys the same information as adding All Swift Platforms as an extra platform.

What we can do is, instead of adding All Swift Platforms, we just add Swift. This avoids the situation of having both Swift and All Swift platforms listed in the same availability description, which could happen if the API defines explicit availability annotation for Swift.

We can add this by default at the module level so that whenever a developer generates documentation with DocC, all the API symbols will be marked with the platform Swift, which indicates that it is available on any platform that supports Swift.

i'm not convinced introducing a pill with Swift version would be an improvement. consider the following scenario:

  • func f() is marked with @available(swift 5.0)
  • the package containing f() uses swift-tools-version: 5.8
  • in reality, the package only compiles at all with a Swift 5.10 toolchain, due to a single occurrence of, say, a namespaced protocol

in this scenario, showing Swift 5.0+ is actively misleading.

As far as I know, DocC currently supports showing Swift in the availability section, this is not new. If the API is marked with such availability information (@Available(swift, X.Y)), this will be displayed in the final docs.

My recommendation is that, instead of adding an availability badge displaying All Swift Platforms (prob. inaccurate version), we change it to only Swift. I think the final message would be the same ("This framework is supported on any platform that supports Swift").

It's not implemented at the moment, but we can make the necessary changes to allow showing custom platforms without specifying versions, only the platform name.

1 Like

Meeting notes

  • Doug: API availability for cross-platform
    • Summary in post above
    • Daniel: DocC documentation uses “Swift” availability documentation
    • Doug: Hope to adopt this across the Swift ecosystem and for us to set the pattern.
    • Dianna: Could we expand the “*” in the symbol graph?
    • Vera: * not included in the symbol graph
    • Dianna: Can we enable All Swift Platforms by default?
    • Daniel: How does this interact with unavailability?
    • Joe: Swift Package Index tries a compatibility matrix and infers framework availability. Currently no way of specifying platform availability of a framework.
    • Daniel: Could use the swift-tools-version.
    • Dianna: You could have tools specific manifest.
    • Franklin: Could enable All Swift Platforms tag by default, initially without a version number.
    • Dianna: Can also include the availability tokens from source in the declaration in docs.
    • Vera: Also language-specific, APIs callable from Swift but defined in another language.
    • David: Are there cases where you’d want to say that an API or framework is available on Linux, but not Windows, say?
    • Daniel: Support for availability checks for other platforms in code?
    • Franklin: To summarize, enable showing “All Swift Platforms” by default, ability to opt out.
    • Doug: Question of the Embedded platform as well.
    • Vera: Can we add Embedded platform in the language?
    • Doug: Something to figure out.
    • Sofía: Should we allow not including a version number?
    • Joe: All Swift Platforms as a default.
  • Vera: Swift-Markdown versioning
    • Swift-Markdown is popular as a standalone library outside of DocC
    • There was a request to use semantic versioning instead of specifying branches
    • David: With 5.10 release, there is automation in place to automatically create releases, but not semantic versioning
    • Kyle: Can we just use the Swift version number as the semantic version?
    • Franklin: Shall we support scenarios where we want to tag a bug fix release before the next Swift release?
    • Dianna: Can we vend Swift-Markdown as part of DocC?
    • Vera: swift-cmark is also used by SourceKit
    • Daniel: What would be the impact of using a separate versioning system?
    • Vera: More difficult to land changes needed by toolchain vs. other clients.
    • Kyle: Need to think about how that impacts our development branches.
    • Vera: Will create branches to track updates to tags.
  • Dianna: Swift symbol graph extract
    • Currently no way to deduplicate symbols from re-exported frameworks.
    • Daniel: In Swift 6, symbolgraph-extract also respects @_exported imports (behind a feature flag).
    • Franklin: Can these packages use @_documentation(visibility: hidden)?
    • Dianna: Would be difficult to coordinate among all repos owners
    • Rauhul: Also, it’s an underscored attribute.
    • David: Re-exported symbols are part of the module’s interface.
    • Rauhul: NIO split up in small frameworks in order to avoid breaking clients.
1 Like

just to avoid confusion, my suggestion was to vend swift-cmark as part of swift-markdown, not to vend swift-markdown as part of DocC.

1 Like