swift-docc

Swift DocC Documentation

DocC compiles /// comments and .docc catalog files into a navigable hierarchy: landing page → articles → symbol pages. A ## Topics group is what places a symbol in that hierarchy — without it, DocC renders the symbol but nothing links to it from the navigation tree.

Step 1: Identify the scope

Completion criterion: you know which output type(s) you will produce before writing anything.

Step 2: Write symbol documentation

Use /// (triple-slash only — never /** */). The comment must be directly adjacent to the declaration with no blank line between them.

/// One-sentence abstract describing what this does.
///
/// Extended discussion — one or more paragraphs. Markdown works here:
/// **bold**, _italic_, `inline code`.
///
/// > Note: Appears as a blue callout. Also: Warning, Important, Tip, Experiment.
///
/// Link symbols with double backticks: ``OtherType`` or ``OtherType/method(_:)``.
/// Link articles with: <doc:ArticleName>.
///
/// ```swift
/// let result = try client.fetch(request)
/// ```
///
/// - Parameters:
///   - paramName: What this parameter represents.
///   - another: Another parameter.
/// - Returns: What the return value represents (omit if obvious from the abstract).
/// - Throws: ``MyError/notFound`` when the resource does not exist.
public func fetch(_ request: Request) throws -> Response { ... }

Rules:

• Abstract is the first non-blank /// line. It appears in every reference to this symbol.
• - Parameters: children are indented two spaces: - name: description.
• - Returns: only when the return value adds information beyond the abstract.
• - Throws: only when the method can throw. List each error case.
• Properties and enum cases need only the abstract — skip Parameters/Returns.
• No @param, @return, @throws — those are Objective-C javadoc style.

Completion criterion: every public symbol in scope has an abstract; methods with parameters have a - Parameters: block; all thrown errors are listed under - Throws:.

Step 3: Add Topics to build the hierarchy

Without a ## Topics section, a type's members appear on its page but are not surfaced in the navigation sidebar or article links. Write Topics either inline in the source or in an extension file.

Inline (on the type itself):

/// The main networking client.
///
/// ## Topics
///
/// ### Creating a Client
/// - ``init(configuration:)``
///
/// ### Making Requests
/// - ``fetch(_:)``
/// - ``upload(_:data:)``
public struct NetworkClient { ... }

Extension file (NetworkClient.md in the .docc catalog):

# ``NetworkClient``

@Metadata {
  @DocumentationExtension(mergeBehavior: append)
}

## Topics

### Creating a Client
- ``init(configuration:)``

### Making Requests
- ``fetch(_:)``
- ``upload(_:data:)``

mergeBehavior: append adds the Topics without touching the in-source summary. mergeBehavior: override replaces the in-source documentation entirely.

Completion criterion: every type that owns child symbols has a ## Topics section listing all public members under named groups.

Step 4: Create a documentation catalog (when needed)

A catalog is a folder ModuleName.docc placed inside Sources/ModuleName/:

Sources/Auth/Auth.docc/
├── Auth.md        ← landing page
└── Resources/     ← images, videos (optional)

Landing page (Auth.md):

# Auth

@Metadata {
  @TechnologyRoot
}

One-sentence module summary.

## Overview

One or more paragraphs introducing the module.

## Topics

### Essentials
- ``AuthClient``
- ``AuthClientConfiguration``

### Session Management
- ``Session``
- ``User``

@TechnologyRoot marks this as the module root. Without it, DocC may not render it as a top-level entry point in Xcode or the web output.

Completion criterion: the catalog folder exists and the landing page compiles without warnings.

Step 5: Verify

./scripts/test-docs.sh

If ./scripts/test-docs.sh is unavailable:

swift package generate-documentation --target ModuleName 2>&1 | grep -E "warning:|error:"

Fix every warning before declaring done.

Completion criterion: the documentation build exits 0 with no warnings.

---

Common mistakes

---

Metadata directives reference

Symbol link path syntax

``TypeName``
``TypeName/propertyName``
``TypeName/methodName()``
``TypeName/methodName(_:secondLabel:)``
``TypeName/init(label:)``