Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

Modern Swift Documentation

Modern Swift documentation has two layers:

Human-facing guides: README, tutorials, architecture notes, examples
API/reference docs: generated from source using Swift documentation comments

What Should Be Documented

Modern Swift documentation should describe:

the purpose of a type, protocol, function, method, property, or enumeration
ownership or lifetime expectations when relevant
preconditions and postconditions
error behavior
thread-safety or actor/concurrency behavior when relevant
performance or complexity when relevant
examples of use

This aligns better with how modern Swift libraries are read and maintained. Swift commonly uses specially formatted documentation comments written directly in the source code. Tools such as Quick Help, Xcode, and Swift-DocC can read these comments and generate API documentation automatically.

Swift Documentation Comments

Swift commonly uses line documentation comments such as /// placed immediately before a declaration. These comments can include Markdown formatting and special fields such as Parameters:, Returns:, Throws:, and - Warning:.

For example, a documentation comment for a function might look like this:

/// Computes the area of a circle.
///
/// Uses the standard formula pi * r^2.
///
/// - Parameter radius: Radius of the circle in meters. Must be non-negative.
/// - Returns: Area in square meters.
/// - Throws: An error if `radius` is negative.
func circleArea(radius: Double) throws -> Double {
    guard radius >= 0 else {
        throw CircleError.negativeRadius
    }
    return Double.pi * radius * radius
}

This is a typical Swift documentation block. Unlike normal comments (// or /* */), this style signals to documentation tools that the text inside should be parsed and included in generated API documentation.

The comment is placed immediately before the function declaration, which tells documentation tools that the text applies to that function.

The first sentence provides a short summary of the function.

Most documentation systems display the summary description in:

function and method lists
summary tables
Xcode Quick Help popups

The summary should explain what the function does, not how it works internally.

After the summary line, you can include additional explanatory text.

This section may describe:

the algorithm used
important assumptions
behavior that may not be obvious

Documentation tools treat this as the detailed description of the function.

The - Parameter field documents each formal parameter of the function. For multiple parameters, Swift also supports a - Parameters: section with an indented list.

Good parameter documentation usually explains:

the meaning of the parameter
valid value ranges
units of measurement (if relevant)
any constraints or requirements

Each function parameter should normally have its own entry.

The - Returns: field explains what value the function returns.

It should describe:

what the returned value represents
the units of the result if applicable
any special values that might be returned

Even if the return type is obvious from the code, describing the meaning of the result is helpful for readers.

The - Throws: field documents errors that the function may throw.

It should include:

the kind of error
the conditions under which it occurs

This helps programmers understand the error conditions that must be handled when calling the function.

Structured comments like this serve several purposes:

Readable source code documentation
Automatically generated API reference manuals
Improved IDE tooltips and code navigation
Clear documentation of interface contracts

Tools such as Xcode Quick Help and Swift-DocC can scan these comments and generate HTML or browsable documentation directly from the source code.

Structures, classes, enumerations, protocols, and generic types can also have documentation comments placed before them. For example:

Structure Example

/// Represents a bank account with a running balance.
///
/// Instances of this type are not thread-safe unless externally synchronized.
struct Account {
    private var balance: Double = 0

    /// Deposits money into the account.
    ///
    /// - Parameter amount: Amount to deposit. Must be positive.
    mutating func deposit(amount: Double) {
        balance += amount
    }

    /// Returns the current balance.
    ///
    /// - Returns: Current balance in dollars.
    func getBalance() -> Double {
        balance
    }
}

Enumeration Example

/// States a task can be in during execution.
enum TaskState {
    /// Task has not started yet.
    case pending

    /// Task is currently executing.
    case running

    /// Task finished successfully.
    case complete

    /// Task ended with an error.
    case failed
}

Generic Type Example

/// Returns the larger of two values.
///
/// - Parameters:
///   - a: First value.
///   - b: Second value.
/// - Returns: The larger of `a` and `b`.
func maxValue<T: Comparable>(_ a: T, _ b: T) -> T {
    return a >= b ? a : b
}

Generic comments in Swift usually explain the role of the type parameter in prose rather than with a special tag like Java's @param <T>. The generic constraint, such as T: Comparable, is part of the signature and often deserves explanation if it is not obvious.

Swift also supports documenting modules, protocols, and properties.

Protocol Example

/// Defines a simple shape with an area.
protocol Shape {
    /// Computes the area of the shape.
    var area: Double { get }
}

Property Example

/// The current balance in dollars.
var balance: Double

Modern docs are much easier to learn from when each API item includes a short usage example.

/// Converts a string to uppercase.
///
/// Example:
/// ```swift
/// let s = toUpper("Hello")
/// // s == "HELLO"
/// ```
///
/// - Parameter text: Input text.
/// - Returns: Uppercase copy of the input text.
func toUpper(_ text: String) -> String {
    return text.uppercased()
}

In Swift documentation comments, Markdown fenced code blocks are commonly used to show code examples.

These examples preserve whitespace and formatting and are displayed clearly in generated documentation.

Inline code fragments are typically written using backticks, such as `Double` or `Comparable`.

Combined, these techniques make it safer and cleaner for showing program code in documentation.

Generating Documentation with Swift Tools

Once your Swift code contains documentation comments, you can automatically generate browsable documentation.

View Documentation in Xcode Quick Help

If you are using Xcode, documentation comments are available directly through Quick Help. Option-click a symbol name in the editor to view its documentation.

Generate Documentation with Swift-DocC

For Swift packages and larger projects, Swift-DocC can build a browsable documentation archive.

Linux and
Raspberry Pi

$ swift package generate-documentation

macOS

% swift package generate-documentation

Windows

> swift package generate-documentation

This tells Swift Package Manager and DocC to build documentation for the current package.

Preview Documentation Locally

You can also preview the generated documentation in a local web server:

Linux and
Raspberry Pi

$ swift package --disable-sandbox preview-documentation

macOS

% swift package --disable-sandbox preview-documentation

Windows

> swift package --disable-sandbox preview-documentation

This builds the documentation and starts a local preview server so you can browse it in a web browser.

View the Generated Documentation

The generated documentation can be viewed in Xcode, in the DocC archive output, or through the local preview server, depending on your workflow.

References

[[Swift Community]]
[[Swift Language Guide]]
[[Swift Language Reference]]
[[Swift Programming Language]], Apple Inc.
[[Swift Doc]]
[[We Heart Swift]]
[[Swift Cookbook]]
[[Swift Playground]]
[[Swift at TutorialsPoint]]
[[Hacking with Swift]]