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()``

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.

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.

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

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.

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)

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

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

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

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

Thank you!

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.

• Allow for emission of swift.extension symbols for extensions to external types in SymbolGraphGen swift#59047
• Make Symbol Graph Format Extensible swift-docc-symbolkit#39
• Adapt Symbol Graph Format to Changes Introduced in apple/swift#59047 swift-docc-symbolkit#45
• MergeStrategy with ExtensionGraphAssociation Option for GraphCollector swift-docc-symbolkit#48
• Extensions to External Types (Hierarchical) #369
• Adapt memberOf Relationships Stemming from Default Implementations to Extension Block Symbol Format 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.

• Make emission of extension block symbols a formal feature swift#61637
• Add support for -emit-extension-block-symbols and -omit-extension-block-symbols flags swift-driver#1205
• Fix "Add emit extension block symbols option to dump-symbol-graph and SymbolGraphOptions" swift-package-manager#5978 (Swift 5.8 backport: Fix "Add emit extension block symbols option to dump-symbol-graph and SymbolGraphOptions" swift-package-manager#5985)
• Add --include-extended-types flag swift-docc-plugin#34

Bugs/Bugfixes

There are two bugs currently known:

• Extension Block Symbols: Fix inheritsFrom Relationship  swift#61951
• Fix Representation of Extensions Across Exported Imports in the Extension Block Symbol Format swift#62409

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

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?

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

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

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

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