Swift snippets

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.

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

Other changes in Swift 5.7…

• if let shorthand for unwrapping optionals
• Multi-statement closure type inference
• Clock, Instant, and Duration
• Regular expressions
• Type inference from default expressions
• Concurrency in top-level code
• Opaque parameter declarations
• Structural opaque result types
• Unlock existentials for all protocols
• Lightweight same-type requirements for primary associated types
• Constrained existential types
• Distributed actor isolation
• buildPartialBlock for result builders
• Implicitly opened existentials
• Unavailable from async attribute

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

Browse changes in all Swift versions