Extending the `@_documentation` attribute to annotate API variants

Evolution Pitches
1

here’s something i do a lot.

/// Some
/// 
/// Long 
/// and
/// detailed
/// documentation.
public mutating
func merge(appending other:Self)
{
}

/// See ``merge(appending:)``.
public consuming
func merged(appending other:Self) -> Self
{
    self.merge(appending: other)
    return self
}

but it would be nice to do this in a machine-readable manner, perhaps using the @_documentation attribute.

@_documentation(see: merge(appending:))
public consuming
func merged(appending other:Self) -> Self
{
    self.merge(appending: other)
    return self
}

it might be possible to do this at the engine level, by repurposing the metadata field.

@_documentation(metadata: "see: merge(appending:)")

but then every documentation engine would have a different convention for these kinds of annotations.

what do we think?

4 Likes
2

I do that a lot as well and I've resorted to duplicating the summaries because I wanted to have at least something in code completion.

It could display the other symbol's documentation with a remark about where it's coming from?

I'd go for the first one because it's more explicit.

2 Likes
3

yeah, the problem i’ve run into is i inevitably forget to keep the duplicated summaries in sync, or worse, i get tempted to intentionally replace a few words in each duplicated paragraph to make it a little more specific to the symbol.

1 Like
4

This is an age-old problem, in pretty much every programming language. I'd love to see it given some love in Swift.

It's important that the solution result in the documentation appearing in full in the various places, not merely show some link or other means of manual redirection. Optionally with a subtle nod to the canonical version.

e.g. I option-click a map method invocation and it shows me the actual map docs from Sequence.map, with a little note at the bottom saying "From conformance to Sequence" or somesuch.

Excitedly thinking further ahead, there's obvious additional enhancements to be made too, like providing some way to say "see <parent / protocol's docs> but aspect XYZ is slightly different / additional usage note / etc". e.g. docs as for Sequence.map but with a type-specific note about the time complexity of the specific implementation in question.

3 Likes
5

What of the - SeeAlso: doccomment callout?

6

documentation inheritance is computed by lib/SymbolGraphGen before markdown parsing takes place, because it is the markdown doccomments that are being inherited.

1 Like
7

I run in to cases all the time where I want to share documentation across different identifiers.

For prior art, JSDoc calls this @inheritdoc.

2 Likes