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.
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.
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
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.
I was recently hitting this very same topic while doing some library documentation work, and thought I might tuck the extended types at the bottom of the general library documentation space.
That said, I don't think docc is pumping the symbols out to where they can be referenced yet either. (I couldn't get anything to properly reference when I tried to manually inject a symbol like AppKit/NSColor/init(_:_:_:_) into my markdown files to reference the extension initializer added in the library - and if there's a hash associated with it (probably), I've no idea what it would be. The data.json files dumped into the preview are only for the library, nothing for extensions that I spotted.)
I don't have a firm opinion on where the content should go, but it's important to some of the usage of the library API to be able to reference the extensions to public/external extensions.
Some of this gets a little tricky though - for example, some of the extensions are specific to when AppKit is imported, and others are only relevant in the UIKit/Catalyst import world. I'm leaning towards the "document them all, just break them up visually", grouping them by the technology/framework that they're extending (AppKit, UIKit, SIMD, SceneKit, etc).
I'm curious what other's have aimed at doing, or what previous documentation has done, when extending system types and documenting it. Was there a pattern that was commonly used with tools like Jazzy?