Using Snippets in Documentation Comments not possible?

Jeehut · 2023-05-18T12:53:33.151Z

The way I read SE-0356 it should be possible to create a snippet file in the Snippets folder of a Swift package and then reference that in my documentation comments via @Snippet.

But that doesn't seem to work the way I expected (with Xcode 14.3 / Swift 5.8):

The @Snippet gives me the warning: "Directives are not supported in symbol source docs"
Showing the Quick Help of my documented type doesn't include the snippet.
Using the menu "Product" > "Build Documentation" produces docs without the snippet.

Bildschirmfoto 2023-05-18 um 14.27.541722×1162 138 KB

Bildschirmfoto 2023-05-18 um 14.31.412074×1298 178 KB

I really thought the Snippets proposal was about "(m)aking it easy to add code listings to documentation that can also be built and run (and validated)", there's an entire section about code listings, but they don't seem to work? Or is it not shipped yet? Or am I misunderstanding something here?

And I was wondering why Point-Free wasn't using them in their sometimes extensive code examples for their inline documentation. I really would love to make sure my inline documentation code listings are compiled so I can be sure users can copy & paste them and all will work fine, so I can confidently improve APIs and refactor code without breaking the docs!

tevelee · 2023-05-18T13:19:57.701Z

It seems like the proposal has only been accepted, but not yet been implemented.

Jeehut · 2023-05-18T13:26:05.711Z

Then, why are people stating it has already shipped?

DocC Snippets - snippet reference not resolved

(...) snippets are compiling without issue both in Xcode, and directly using swift (...)

Using snippets with Swift-DocC

(...) snippets have been available in Xcode and toolchains for a while (...)

mbrandonw · 2023-05-18T14:30:01.518Z

It looks like it doesn't work from Xcode yet. You need to build the docs from the command line:

swift package generate-documentation

Or startup a server to host the docs:

swift package --disable-sandbox preview-documentation --target FreemiumKit

A nice thing about preview-documentation is that it automatically rebuilds docs whenever you save a file, but unfortunately that does not seem to include snippets. I have to restart the server each time I make a change to a snippet to actually see the change.

Hopefully this gets better, or we get Xcode integration soon.

bitjammer · 2023-05-18T18:50:56.728Z

Snippets were implemented in Swift 5.7 and are available with SwiftPM via swift-docc-plugin but, as others have pointed out, there isn't integration with Xcode-based documentation workflows as that uses a different build system. I'll update the proposal.

That doesn't address the original question as to whether the @Snippet directive should be allowed in doc comments, as all directives are disallowed there. I wouldn't be opposed to allowing them, but the question of what to do with all of the other directives might need discussion. Could be as simple as an allow list that starts with @Snippet. Thoughts on that?

Jeehut · 2023-05-18T18:59:35.127Z

Thank you for the clarification. It’s a pity that we don’t have support in Xcode yet, but maybe it changes this year? Hoping for it!

bitjammer · 2023-05-18T19:21:11.170Z

To track allowing some directives in doc comments, see this issue: Allow certain directives in doc comments · Issue #591 · apple/swift-docc · GitHub

Jeehut · 2023-05-18T19:23:02.970Z

@bitjammer Thank you for creating the issue!

mbrandonw · 2023-05-18T19:39:21.583Z

Hi @bitjammer, is it also worth an issue to regenerate docs when a snippet changes while running preview-documentation? I found that changing the snippet Swift file doesn't trigger a rebuild, but even worse, if I change the snippet file and then make a change to the docs (thus triggering a rebuild), the updated snippet does not show. I have to actually kill the server and restart it to see the snippet changes.

bitjammer · 2023-05-18T19:40:51.802Z

Yes, please do–and thank you!

mbrandonw · 2023-05-18T19:46:46.116Z

Great thanks, done here.