SE-0356: Swift Snippets
This proposal at first might sound like the Xcode snippets
feature, I personally even thought (or hoped?) it was related to Swift scripts
in some way. But none of that is true. This proposal is mostly aimed at library authors and provides them with another way to document functionality. This sentence in the proposal summarizes the direction of the feature pretty well, I think:
Making it easy to add code listings to documentation that can also be built and run (and validated) is one of the main goals of snippets.
While sample projects
are great to show off how everything fits together, they are hard to maintain and don’t help with exploration to potential users. Extensive code examples
right within documentation comments are much more explorable because you can easily show them via alt-clicking APIs right within Xcode when you need them. But from the compiler’s view, they are just plain Strings, and thus when you make changes to your APIs, it’s easy to forget to update the related code examples accordingly and they get outdated.
Snippets fix the latter. You provide them as separate files in a
Snippets folder within your Swift package & you can also group them, like so: