apple/swift-docc

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

swift-ci opened this issue · 18 comments

swift-ci commented
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.

Kyle-Ye commented

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 commented

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 commented

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 commented

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

swift-ci commented

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.

  • 👍1
Kyle-Ye commented

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 commented

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

QuietMisdreavus commented

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

LeoNatan commented

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

theMomax commented

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

  • 👍1
LeoNatan commented

Thank you!

theMomax commented

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.

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.

Bugs/Bugfixes

There are two bugs currently known:

QuietMisdreavus commented

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

adamwulf commented

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 commented

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

  • 🚀1
adamwulf commented

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

  • ❤️1
theMomax commented

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

adamwulf commented

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

  • ❤️2