WWDC22 SALE: Save 50% on all my Swift books and bundles! >>

Swift snippets

Available from Swift 5.7

Paul Hudson      @twostraws

SE-0356 introduces the concept of snippets, which are designed to fill a small but important documentation gap for projects: sample code bigger than simple API documentation, but smaller than an example project, designed to show off one specific thing in your project.

On the surface that seems simple enough, and you can certainly imagine providing snippets that demonstrate a single API, or a solution for a particular problem, but there are three things that make snippets particularly interesting:

  1. There’s a small amount of special markup you can place inside comments to adjust the way snippets are rendered.
  2. You can build and run them easily from the command line.
  3. They integrate beautifully into DocC, and are rendered alongside the rest of your documentation.

The special markup comes in two forms: you can use //! comments to create a short description for each snippet, and you can use // MARK: Hide and // MARK: Show to create invisible blocks of code, for when you need to do some work that isn’t specifically relevant to whatever your snippet is trying to demonstrate.

So, we could create a snippet like this:

//! Demonstrates how to use conditional conformance
//! to add protocols to a data type if it matches
//! some constraint.

struct Queue<Element> {
    private var array = [Element]() 
    // MARK: Hide

    mutating func append(_ element: Element) {
        array.append(element)
    }

    mutating func dequeue() -> Element? {
        guard array.count > 0 else { return nil }
        return array.remove(at: 0)
    }
    // MARK: Show
}

extension Queue: Encodable where Element: Encodable { }
extension Queue: Decodable where Element: Decodable { }
extension Queue: Equatable where Element: Equatable { }
extension Queue: Hashable where Element: Hashable { }

let queue1 = Queue<Int>()
let queue2 = Queue<Int>()
print(queue1 == queue2)

That uses // MARK: Hide and // MARK: Show to hide some implementation details, letting readers focus on the part that matters.

As for the command-line support, we can now run three new command variations:

  • swift build --build-snippets to build all your source targets including all your snippets # Builds source targets, including snippets.
  • swift build SomeSnippet to build SomeSnippet.swift as a standalone executable.
  • swift run SomeSnippet to run SomeSnippet.swift immediately.

Each snippet you create can access all the code you’ve created in the rest of your package, meaning that they are just fantastic ways of providing hands-on example code for various parts of your projects.

Hacking with Swift is sponsored by RevenueCat

SPONSORED You know StoreKit, but you don’t want to do StoreKit. RevenueCat makes it easy to deploy, manage, and analyze in-app subscriptions on iOS and Android so you can focus on building your app.

Explore the docs

Sponsor Hacking with Swift and reach the world's largest Swift community!

Other changes in Swift 5.7…

Download all Swift 5.7 changes as a playground Link to Swift 5.7 changes

Browse changes in all Swift versions

 
Unknown user

You are not logged in

Log in or create account
 

Link copied to your pasteboard.