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.
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!
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.
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?
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.
