Document Extension file can document multiple symbols in one file?

Development Swift-DocC
1

Hello,
I'm on trying to separate every document comments from .swift to .docc.
I thought that Document Extension file can satisfy my goal.
But as I know, I should create separated Document Extension files for each symbols.
For example, Activity protocol on this sample project.
https://developer.apple.com/documentation/xcode/slothcreator_building_docc_documentation_in_xcode

Activity.swift

/// A type that declares an activity a Sloth can perform.
public protocol Activity {
    /// Performs the work or sequence of actions for an activity.
    ///
    /// - parameter sloth: The sloth performing the activity.
    /// - returns: The speed at which the sloth performs the activity.
    func perform(with sloth: inout Sloth) -> Speed
}

If I want to move every document comments to .docc, I should create two Document Extension files.

Activity.md

# ``SlothCreator/Activity``

A type that declares an activity a Sloth can perform.

Activity_perform.md

# ``SlothCreator/Activity/perform(with:)``

Performs the work or sequence of actions for an activity.

- parameter sloth: The sloth performing the activity.
- returns: The speed at which the sloth performs the activity.

Then I can remove every document comments from Activity.swift.

Activity.swift

public protocol Activity {
    func perform(with sloth: inout Sloth) -> Speed
}

Is there any way to document multiple symbols in one Document Extension file? (to combine Activity.md and Activity_perform.md to one file)

2

No, there is no way to document multiple symbols in the same documentation extension file. More on why below.

In Swift-DocC, the primary source for "reference documentation" (documentation about specific symbols) is in-source documentation comments. Very loosely described, the idea is that the brief descriptions about a symbol and its inputs and outputs is written right next to that symbol. This makes the documentation available to developers reading the code without needing to open another window and context switch.

This works well for most symbols which only need a couple of paragraphs to explain well. However, for some symbols—which benefit from longer explanations, code examples, illustrations etc.—the in-source documentation grows to a point where it starts to get in the way and there could be a reluctance to write more documentation (which we don't want there to be). It's for this problem that we designed documentation extensions; to allow the developer to keep the brief descriptions in the in-source documentation comments and also write additional long-form documentation for the rendered version of the symbol's documentation.

Depending on personal preference for how long in-source documentation should be, the rough idea is that the majority of symbols wouldn't need a documentation extension and that many of the symbols who benefit from a documentation extension would have a couple of paragraphs or more, maybe a code example, and maybe organization of topics. Because very few documentation extensions would be "short" (e.g. only a few lines) we didn't see a strong need for writing multiple documentation extensions in a single file.

I'd be curious to know if there are specific reasons for wanting to remove every documentation comment from the source code.

4 Likes