Hi everyone!
Back in March I pitched Documenting Extensions to External Types using DocC. Today, over nine months, and twelve PRs to six repositories later, development is completed and I'm happy to announce it's finally time for you to try it out!
Before I get into the details of using it, I want to thank everyone who's helped me along the way, by participating in discussions, reporting bugs, reviewing PRs, or otherwise. Special thanks to @daniel-grumberg, @ronnqvist, @ethankusters, @franklin, and @QuietMisdreavus, this would not have been possible without you!
Finally, please note that this discussion is about enabling extension support as an opt-in feature, not as a default. I'll go into more detail about this at the end of this post.
How to try it
- Use a toolchain generated from
mainorrelease/5.8branches after January 7th. You can download it here. - Use the
add-extended-types-flagbranch of my fork of the DocC plugin when adding theswift-docc-pluginto yourPackage.swift:
dependencies: [
.package(url: "https://github.com/themomax/swift-docc-plugin", branch: "add-extended-types-flag")
]
- Add the
--include-extended-typesflag when running your commands. E.g. you can run the following command to preview your documentation in the browser:
swift package --disable-sandbox preview-documentation --target YOUR_TARGET_NAME --include-extended-types
For further instructions on how to use the DocC Package Plugin in general, run swift package plugin generate-documentation -h, or find the documentation online.
You should now see any (public) extensions you've made in the target you're documenting to types from other targets in your documentation archive.
You should now see a new section "Extended Modules" in your module's top-level documentation page, as well as in the sidebar. This section lists all the targets you've added public extensions to. You can start exploring the "Extended Types" and the symbols you extended them with by digging into the page-hierarchy.
You can refer to these new symbols using the following formats:
- relative:
ExtendedModuleName/ExtendedType/extensionSymbol - absolute:
/ExtendingModuleName/ExtendedModuleName/ExtendedType/extensionSymbol
Here's a quick example with a small extension to the standard library:
/// This comment will be used in the documentation
/// archive to document the "Extended Struct" `Int`.
extension Int {
/// This comment documents the added symbol as usual.
public var isEven: Bool { self % 2 == 0 }
}
/// We can refer to the extension on `Int`
/// as ``Swift/Int/isEven``.
public struct MyStruct { }
We can override or append to the documentation for the "Extended Struct" Int, its property isEven and the "Extended Module" Swift using a Markdown file in your Documentation Catalog as usual:
Assuming the target we're documenting is called SampleTarget, the Markdown file containing the documentation for the "Extended Module" Swift should start with the following line:
# ``SampleTarget/Swift``
Curation, i.e. altering the hierarchy of documentation pages in your Documentation Archive also works as usual using absolute or relative references.
Please try it out and post your feedback here! I'd also love if you could share links to some documentation archives you updated with this feature!
Enablement Plans
The Documentation WG plans to make this feature available via the non-experimental feature-flag --include-extended-types in Swift 5.8. In case this discussion reveals that there is a lot to be fixed, we might opt for adding an experimental prefix to the flag, or postponing the release of this feature to the next minor version of Swift.
Depending on the experience we make with the feature in Swift 5.8 and its popularity among documentation authors, we might make this feature the default behavior in a future version of Swift. However, this is to be decided on another day.
Looking forward to your feedback!
Cheers
~ Max
, thanks for all your hard work! I finally have proper documentation for my Swift extensions package - link to the fresh new documentation: 
