Dunfey · Hotel WWDC as data, est. 1983
Front desk everything
Years
Topics

2021 EssentialsDeveloper Tools

WWDC21 · 23 min · Essentials / Developer Tools

Meet DocC documentation in Xcode

Discover how you can use DocC to build and share documentation for Swift packages and frameworks. We’ll show you how to begin generating documentation from your own code — or from third-party code you depend upon — and write and format it using Markdown. And we’ll also take you through the export process, helping you generate DocC archives to share with the public.

Watch at developer.apple.com ↗

Transcript all transcripts

Code shown on screen · 8 snippets

Existing comments in code swift · at 9:34 ↗
// A model representing a sloth.
public struct Sloth {
    // ...
}
Writing documentation comments swift · at 10:05 ↗
/// A model representing a sloth.
public struct Sloth {
    // ...
}
Writing block-style documentation comments swift · at 10:22 ↗
/** 
 A model representing a sloth.
 */
public struct Sloth {
    // ...
}
Documenting the Food struct swift · at 11:34 ↗
/// Food that a sloth can consume.
///
/// Sloths love to eat the leaves and twigs they find in the rainforest canopy as they
/// slowly move around. To feed them these items, you can use the `twig`,
/// `regularLeaf` and `largeLeaf` default foods.
///
/// ```swift
/// superSloth.eat(.twig)
/// ```
public struct Food {
		// ...
}
Documenting the Sloth.sleep(in:for:) method swift · at 13:58 ↗
/// A model representing a sloth.
public struct Sloth {
    /// Sleep in the specified habitat for a number of hours.
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}
Documenting the Sloth.eat(_:quantity:) method swift · at 15:39 ↗
/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// - Parameters:
    ///   - food: The food for the sloth to eat.
    ///   - quantity: The quantity of the food for the sloth to eat.
    /// - Returns: The sloth's energy level after eating.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}
Adding symbol links to the documentation for Sloth.sleep(in:for:) swift · at 17:46 ↗
/// A model representing a sloth.
public struct Sloth {
    /// The energy level of the sloth.
    public var energyLevel: EnergyLevel

    /// Sleep in the specified habitat for a number of hours.
    ///
    /// Each time the sloth sleeps, their ``energyLevel`` increases every hour by the
    /// habitat's ``Habitat/comfortLevel``.  
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}
Adding symbol links to the documentation for Sloth.eat(_:quantity:) swift · at 18:44 ↗
/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// When they eat food, a sloth's ``energyLevel`` increases by the food's
    /// ``Food/energy``. 
    ///
    /// - Parameters:
    ///   - food: The food for the sloth to eat.
    ///   - quantity: The quantity of the food for the sloth to eat.
    /// - Returns: The sloth's energy level after eating.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}

Resources