Setting (programming) language availability for articles in Swift-DocC

Development Swift-DocC
1

Hello! I’m here to propose a new feature for Swift-DocC: setting language availability for article content. Right now, Swift-DocC will mark an article as being available for each language that has a symbol in the module, but sometimes this isn’t accurate.

Proposed solution

To resolve this, i would like to add a directive to the page metadata: @SupportedLanguages. This would take one or more language identifiers to tell Swift-DocC that the article is only meant to be appropriate for the given language(s). It would look like this:

@Metadata {
    @SupportedLanguages(swift)
}

@Metadata {
    @SupportedLanguages(swift, objc)
}

This would only be read on articles - it would be ignored on a symbol page. Leaving this out would continue to use Swift-DocC’s current behavior of adding the article to every available language.

Open questions

  • This is meant to hook into the same kind of language identifiers that would come from a symbol graph - hence swift and objc/occ in the sample. How can we make sure this extends to new languages when people make symbol graphs for something other than Swift or Objective-C?
1 Like
2

I was taking a stab at the implementation of this feature, and I realised that there might be an alternate syntax we could use instead of the proposed one to align better with other directives.

In particular, DocC doesn't currently have a concept of directives with 'variadic arguments' like the one proposed in the original pitch. Taking a look at existing directives for inspiration, it seems like the @Links directive is similar in spirit, in that its goal to list an unbounded number of items.

Are there objections to aligning with that existing model and using the following syntax instead?

@Metadata {
    @SupportedLanguages {
        - swift
        - objc
    }
}
2 Likes
3

That should work! For some reason i'd thought that it was possible to wedge that into the automatic-directive-argument-conversion system, but i guess not. This is still a good version that fits into directives that already exist, which i appreciate.

4

I suspect the most common use of this will be to set a single supported language, even if we eventually have 50 supported languages. Is there a shorthand syntax for that equivalent to the list form shown here? A list of one item looks a bit weird.

3 Likes
5

I agree with this – I also think there isn't actually much precedent for a directive that takes a list of items as configuration. @Links seems similar at first-glance but it's not a configuration directive – it's a rendering directive that maps 1-1 with content on the page. Additionally – it follows the precedent of Topics sections. I think if we take this approach we should consider it an entirely "new" syntax and not a follow-on of @Links.

I'd still prefer the varidaic approach honestly – while it's technically new to DocC I don't think it's conceptually new to DocC since directives are clearly inspired by method calls where folks are used to variadic parameters. As an alternative though – could we just support multiple multiple @SupportedLanguage(_:) directives? That would be more concise even for the 2-language situation.

@Metadata {
    @SupportedLanguage(swift)
    @SupportedLanguage(objc)
}

It also leaves the door open to adding the variadic version in the future if we see a need.

4 Likes
6

These are great points. Introducing variadic parameters to Swift-DocC directives is a slightly larger design problem that is needed for this specific use case I'd say. We need to define rules as to when variadic arguments can be passed, whether you can mix-and-match variadic and non-variadic arguments, what is the interaction with labeled parameters, etc. Something to explore when we have a concrete need for it.