[SR-15410] Can't document extensions with DocC

[apple]

[SR-15410] Can't document extensions with DocC

[adamwulf]

@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!

[swift-ci]

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.

[theMomax]

@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!

[theMomax]

@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.

[adamwulf]

@theMomax Wonderful thanks! Take all the time you need, especially as we approach the holidays 😄 Thanks!

[Kyle-Ye]

I can't reproduce what you describe. rnikander (JIRA User)

I'm trying to reproduce with the SlothCreator demo https://developer.apple.com/documentation/xcode/slothcreator_building_docc_documentation_in_xcode

First I add an extension to Sloth

extension Sloth {
    /// Format the matrix with a default style
    public func formatted() -> String {
        return ""
    }
}

And then I can see it like this

And I can also reference it like this

On Sloth, it is ``formatted()``. On other part of DocC, it is ``Sloth/formatted()``

[swift-ci]

Comment by Robert Nikander (JIRA)

Sorry, I should have been more specific in my bug report. This is about extending types from other packages. That may not be important for the Sloth package, but you can imagine something like the linear algebra package in my example, that extends the simd matrix types. Try extending a system type, or specifically the simd_float3x3 that I used in my example.

[Kyle-Ye]

Yes, I can reproduce this by adding a extension to Int

extension Int {
    /// This is a test function
    public func aa(){
        return
    }
}

But I kindly think it is more of a feature than a bug.

Since the Int or simd_float3x3 is not a structure we define(or in our package). We are not authorised to document this function. Even the function was declared as public.

But yes, we could implement this as long as the code owner of the repo agree on this feature proposal.

[franklinsch]

(Discussion about this topic started in https://forums.swift.org/t/docc-and-extensions/53132)

[Kyle-Ye]

I think https://forums.swift.org/t/docc-and-extensions/53132/4 makes sense to me. We can add the feature / fix the "bug" without significant changes to DocC. The problem is to decide from a UX perspective of how to link to those symbols and render them in the documentation.

I'm glad to hear your suggestion in the forum's discussion on this. rnikander (JIRA User)

[QuietMisdreavus]

The feature's not quite fixed yet; one of its constituent PRs just was.

[QuietMisdreavus]

Once again, there are more PRs to merge before this feature is 100% resolved.

[LeoNatan]

Would Objective C categories be documented when this issue is solved, or is that a completely different set of requirements/bug?

[LeoNatan]

Thank you!

[theMomax]

As per the last Documentation WG discussion, here is a list of completed and remaining work items related to this issue. All PRs and issues are listed in the order in which they should be addressed/merged.

Feature Development

Feature development is basically complete, only one last very small PR needs to be reviewed and merged.

• apple/swift#59047
• apple/swift-docc-symbolkit#39
• apple/swift-docc-symbolkit#45
• apple/swift-docc-symbolkit#48
• #369
• apple/swift#61406

Feature Enablement

Feature enablement is just about adding the command line flags to all the relevant repositories: swift integrated driver, swift-driver, swift-package-manager, and finally swift-docc-plugin.

• apple/swift#61637
• apple/swift-driver#1205
• apple/swift-package-manager#5978 (Swift 5.8 backport: apple/swift-package-manager#5985)
• apple/swift-docc-plugin#34

Bugs/Bugfixes

There are two bugs currently known:

• apple/swift#61951
• apple/swift#62409

[QuietMisdreavus]

Once again, not quite there yet. See @theMomax's last comment for the current status.

[adamwulf]

Is this issue finally closed - I see a few items still unchecked in the todo list above. I'm trying to build and run locally to take advantage of this new feature, but I don't see how to enable it. It appears the flags are still not merged in, is that right?

[theMomax]

The enablement discussion for my implementation has started! Check out the thread here for details on how to use the feature and updates on its enablement in the Swift 5.8 release toolchain.

cc @adamwulf