swift-docc: [SR-15410] Can't document extensions with DocC
| Previous ID | SR-15410 |
| Radar | rdar://63987302 |
| Original Reporter | rnikander (JIRA User) |
| Type | Bug |
Attachment: Download
Additional Detail from JIRA
| Votes | 11 |
| Component/s | Swift-DocC |
| Labels | Bug |
| Assignee | @theMomax |
| Priority | Medium |
md5: 0a7941d59b134a8d6fcab0d5853ef0b5
Issue Description:
I have a Swift package in which I define some extensions on matrix types like simd_float3x3. I tried to use DocC to create documentation for this package, but I can’t get it to show the extensions.
Example of code in my module that I can’t document:
extension simd_float3x3 {
/// Format the matrix with a default style
public func formatted() -> String { ... }
I guessed at some syntax in the markdown files. For example: ``simd_float3x3/formatted``. But I’m not familiar enough with DocC yet to have any suggestions on what the syntax should be.
About this issue
- Original URL
- State: closed
- Created 3 years ago
- Reactions: 1
- Comments: 18 (8 by maintainers)
@theMomax Fantastic! I was just thinking about this again recently, perfect timing 😃 Thanks for the huge effort on this, I’m very excited to start using it!
@theMomax Wonderful thanks! Take all the time you need, especially as we approach the holidays 😄 Thanks!
@adamwulf The Swift compiler flags are merged, so it is technically possible to document extensions with DocC now, but I’m still working on getting the flags into higher-level commands in the Swift Package Manager and the DocC Package Plugin.
There also have been some problems with the recent Trunk Development toolchain builds, so it’s a little tricky to get it working with the public toolchain builds.
Please be patient one more week. I’ll post on the forums once everything is ready.
In the meantime, here is the simplest setup (macOS only, unfortunately):
Package.swiftfile:swiftSettings: [.unsafeFlags(["-emit-extension-block-symbols"])]Product > Build Documentationorxcodebuild docbuild)Note that it might also work with more recent toolchain builds, but that is the last version I tried it with that way.
@LeoNatan this issue only discusses Swift extensions and the solution I’m developing right now also only applies to Swift (although the same approach should also be applicable to Objective C categories). Feel free to open a separate issue for ObjC category support if you have demand for it!
Comment by Robert Nikander (JIRA)
@Kyle-Ye, no, it’s definitely not a “feature”! Swift encourages extensions of types from other modules. Look at SwiftUI - the entire library of “view modifiers” are extensions. Other examples would be an algorithms package that extends the standard collection protocols, or a math package like my example. We need to be able to document code like that.