Customizing symbol availability text

I'm working on a package that uses protocols to affect symbol availability on a couple of key public types. These protocols are used for defining relative ordering of their conformers. For example I know that a type that conforms to LTOEHour is used to express calendar units that are "less than or equal to an hour". Similarly, a type that conforms to GTOEMonth represents calendar units that are "greater than or equal to a month".

These protocols are not ones that package users should adopt, and I've taken steps to ensure they cannot adopt them. They exist largely as implementation details to simplify how method availability is expressed. I've even tagged them as @_documentation(visibility: internal), because I don't want then polluting the documentation and distracting users from understanding the core functionality.

However, these types, despite being visibility: internal, still show up in documentation as part of availability statements. For example, this method…

extension Fixed where Granularity: LTOEDay {
    public var isWeekend: Bool { get }
}

… shows up in the documentation with an availability that says

Available when Granularity conforms to LTOEDay .

I want to change this text to be something like

Available when this fixed value represents calendar values that are at least as specific as a calendar day.

(or something)

@icanzilb pointed out on Mastodon that it's possible to customize this by compiling my own version of DocC, but I'd rather not do that. :sweat_smile:

Is this something that can be added as perhaps an /// - Available: tag, or even a @_documentation(available:) attribute?

2 Likes

I feel this would be a nice small enhancement to allow developers to be more specific or more descriptive than the default generated conditional availability text.

We have a similar situation with deprecation messages which are limited to plain text by the compilers but DocC has a—still "experimental" and hidden from documentation—@DeprecationSummary directive that allow developers to override the deprecation message with one that contains styled text and links to other symbols. I could see us doing something very similar here. The main question is what the syntax would be.

I like @davedelong 's suggestion to have an extra tag that spells out the availability like :

/// - Availability: `Granularity` conforms to `Codable` and it's the second Tuesday of the month.
extension Fixed where Granularity: LTOEDay {
    public var isWeekend: Bool { get }
}

If the Availability tag is used on another node then an extension or a function with custom availability it should produce a warning.

Each of the symbols in the extension should inherit the custom availability message.

I wouldn't go with a @_documentationAvailability(...) attribute or similar as the spelling of the precise availability is probably not a concern of the symbol graph extractor?

If that's implemented as a documentation tag the source changes to implement this would be minimal.

1 Like