Thanks for being a part of WWDC25!

How did we do? We’d love to know your thoughts on this year’s conference. Take the survey here

Can DocC be used to abstract out lines of comments?

I'd like to point to comments about my code from outside the coding file to keep the code easier to read, but still have the comments show in Xcode's Quick Help. I've grown to appreciate lengthier comments, including Examples for demonstrating values that explain what calculations are doing. My DocC formatted comments have quickly reach 25 lines and some would benefit from even more lines than that, which I do not want to bloat my code files with. I have tried to find a way to abstract these lines into a .docc file that references the given property, and the following markdown successfully shows this when I run Build Documentation. However, clicking on this property fails to show any comments in Quick Help, even though they did prior to my moving them to an .md file. Unfortunately, I'd prefer reading these in the future in Quick Help over Xcode's Developer Documentation Window.

I haven't used markdown in decades, so I'm hoping I'm merely making a markdown mistake someone can find below. For reference, InvItem is a SwiftData Model and circularDepletionArcValue is the property failing to show in Quick Help after the following got moved to a .docc file, but had previously shown in QuickHelp, and still does compile within Developer Documentation.

`# ``InvItem/circularDepletionArcValue``

A computed property that determines the fill percentage of a circular arc based on the number of days until the inventory runs out.

## Overview
The calculation follows these rules:
- Returns 0.01 (minimum visible value) for less than 1 day
- Returns 1.0 (full circle) for more than 11 days
- Returns a proportional value between 0.1 and 1.0 for 1-11 days

## Examples
```swift
let item = InvItem()
item.daysTilRunOut = 0
item.circularDepletionArcValue // Returns 0.01

item.daysTilRunOut = 5
item.circularDepletionArcValue // Returns 0.5
item.daysTilRunOut = 12
item.circularDepletionArcValue // Returns 1.0
Answered by DTS Engineer in 835621022

I suspect that this is working as expected. The DocC mechanism for merging supplemental content kicks in when you build the documentation, not during the Quick Help process.

I think it’d be reasonable for you to file enhancement request for Xcode to change that. Please post your bug number, just for the record.

In the meantime, one option is to leave your doc comments in your source file and then learn to love Editor > Code Folding > Fold Comment Blocks.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Accepted Answer

I suspect that this is working as expected. The DocC mechanism for merging supplemental content kicks in when you build the documentation, not during the Quick Help process.

I think it’d be reasonable for you to file enhancement request for Xcode to change that. Please post your bug number, just for the record.

In the meantime, one option is to leave your doc comments in your source file and then learn to love Editor > Code Folding > Fold Comment Blocks.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Thanks Eskimo, I hadn’t realized until your reply that I’ve avoided folding comment blocks from some vague memory of it unfolding, but your suggestion will be less friction than my attempts to recreate the subgroup tree structure in my .docc folder. I’ll just get comfortable with keyboard shortcuts and this approach will be cleaner.

Still filed feedback on this in case there are edge cases this would help at FB17262930

Thanks again

Can DocC be used to abstract out lines of comments?
 
 
Q