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

[swift-ci]

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]

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)

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

[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)