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)

Most upvoted comments

@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):

  • Xcode Version 14.1 (14B47b)
  • Toolchain Swift Development Snapshot 2022-11-03 on macOS Ventura Version 13.0.1 (22A400)
  • Add this to your Package.swift file: swiftSettings: [.unsafeFlags(["-emit-extension-block-symbols"])]
  • build in Xcode (via Product > Build Documentation or xcodebuild 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.