DocC and extensions?

I have a Swift package in which I define some extensions on matrix types like simd_float3x3. I just tried to use DocC to create documentation for this package, but I can't get it to show the extensions? Is that not supported? Eg:

extension simd_float3x3 {
    /// Format the matrix with a default style
    public func formatted() -> String { ... }

I flailed around a bit trying to create links in the DocC markdown files, with syntax like ``simd_float3x3/formatted``, but that doesn't work.

1 Like

DocC currently does not support references to symbols/types defined in other modules, including symbols defined as extensions in the current module.

DocC currently does not support references to symbols/types defined in other modules, including symbols defined as extensions in the current module.

@Mordil is correct here. Although, I would separate those as two separate issues. Linking to symbols defined in other modules is a new feature we would would definitely like to support in Swift-DocC (@Mordil a feature request on bugs.swift.org would be great!), while I would view the behavior @robnik described as a bug. Those symbols are defined in your current module, so DocC should support them even without the cross-module linking feature.

@robnik if you could file a bug on bugs.swift.org with the behavior you’re seeing as well as your proposed solution for link syntax that would be really appreciated! One of things we need to work through here is the UX of how extension symbols would be rendered and linked to.

2 Likes

I definitely agree they're two separate issues, but if I understand correctly, one stems from the other. Since you can't reference a type symbol defined in other modules, there's no way to reference the extension symbols on types defined in other modules - yeah?

I'll try to find time to file a bug on Swift.org, but during the summer I filed FB9410972 regarding this issue as a feature request

Okay, I filed a bug. [SR-15410] Can't document extensions with DocC - Swift

2 Likes

there’s no way to reference the extension symbols on types defined in other modules - yeah?

It’s true that there’s currently no way to reference the extension symbols defined in other modules. I agree, that support would stem from the new feature to support cross-module linking.

However extension symbols defined in the current module but extending a different module can be referenced without significant changes to DocC. That data is already in the symbol graph given to DocC by the Swift compiler, it’s just a matter of deciding from a UX perspective how to link to those symbols and render them in your documentation.

5 Likes

Ah, that’s great to hear!

I filed SR-15431 for the feature request to be able to link to symbols defined in other modules

2 Likes
Terms of Service

Privacy Policy

Cookie Policy