Document Extensions to External Types Using DocC

Development Swift-DocC
,
21

Hi @theMomax! This is looking really great. Thanks for putting so much thought into this.

I've been following the discussion and I think we've arrived at a good solution here. I just have a few clarifying questions.

Are we only including the -swift.module-extension disambiguation suffix if we detect a collision with another top-level symbol? That would follow the way Swift-DocC's type disambiguation suffixes generally work but I wanted to clarify to be sure.

So then the default way to link to an Array extension (assuming you didn't define a top-level Swift symbol) would be:

``Swift/Array/init(_:)``

But in the case where I have defined a collision:

public enum Swift {
    case foo
}

I would have:

``Swift-swift.enum/foo``

and

``Swift-swift.module-extension/Array/init(_:)``

This follows the way Swift-DocC currently handles collisions as documented here: DocC Documentation: Link to Symbols and Other Content. So we would get this behavior effectively for "free" if we start including module extension symbols in the primary symbol graph.

The alternative of always including the disambiguation suffix would lead to a somewhat clunky authoring experience since developers would need to write out the full Swift-swift.module-extension suffix whenever they're referencing an extension symbol in their current package.

I'm also wondering if we should consider adjusting the disambiguation suffix to be -swift.module.extension since I think this follows the existing disambiguation suffixes a little better (like -swift.enum.case).

On another topic- it seems like the proposed solution here is to add two new symbol kinds to the primary symbol graph for a module that includes extensions:

  • module.extension
  • extension

The first to refer to the containing module and the second to refer to the symbol being extended. Is this right?

I'm wondering if we should have more nuanced kinds for the symbols being extended. I'm imagining we'll have auto-curation something like this:

<!-- SlothCreator.md -->

# Sloth Creator

## Topics

### Structures

...

### Protocols

...

### Extended Modules

- ``Swift``
- ``SwiftUI``

<!-- Swift.md -->

# ``Swift``

## Topics

### Extended Symbols

- ``Int``
- ``Sequence``
- ``Array``

But it might be nice to be able to support:

<!-- Swift.md -->

# ``Swift``

## Topics

### Extended Protocols

- ``Sequence``

### Extended Structures

- ``Int``
- ``Array``

This would also allow us to to put something like "Extended Structure" in the eyebrow text for the Int and Array pages instead of just "Extended Symbol".

Maybe we should just introduce an extension suffix to the existing kinds in the symbol graph?

So we would have:

- `swift.struct.extension`
- `swift.protocol.extension`

Instead of a more generic:

- `swift.extension`

Thank you again for putting this together! I'm really looking forward to being able to document extensions with Swift-DocC.

2 Likes