swift-docc

Swift DocC Documentation

Comprehensive DocC documentation skill for creating rich API documentation and interactive tutorials.

Overview

Target Platform: iOS 17+ / macOS 14+ / Swift 5.9+

Core Capabilities:

• Documentation comments (`///` and `/** */`)
• DocC catalog creation and organization
• Articles and interactive tutorials
• GitHub Pages hosting and CI/CD

Quick Start Checklist

1. Add documentation comments to public APIs using `///`
2. Create DocC catalog at `Sources/[Target]/Documentation.docc/`
3. Build documentation: Product → Build Documentation (⌃⇧⌘D)
4. Preview: The documentation opens in Developer Documentation window

Documentation Comments

Basic Syntax

Use triple-slash (`///`) for single-line or multi-line documentation:

```swift /// A geographic location with a human-readable name. /// /// Use `Place` to represent locations throughout the application. /// This type is optimized for use with MapKit. /// /// ## Example /// /// ```swift /// let tokyo = Place(name: "Tokyo", coordinate: .init(latitude: 35.68, longitude: 139.76)) /// ``` struct Place { /// The display name of this location. var name: String

/// The geographic coordinate of this location.
var coordinate: CLLocationCoordinate2D

} ```

Parameter Documentation

Document parameters, return values, and thrown errors:

```swift /// Calculates the route between two locations. /// /// - Parameters: /// - source: The starting location. /// - destination: The ending location. /// - transportType: The preferred transport method. Defaults to `.automobile`. /// /// - Returns: A `Route` containing the calculated path and estimated time. /// /// - Throws: `RoutingError.noRouteFound` if no valid route exists. /// /// - Note: This method requires network connectivity. func calculateRoute( from source: Place, to destination: Place, transportType: MKDirectionsTransportType = .automobile ) async throws -> Route ```

Callouts

Use callouts to highlight important information:

```swift /// Saves the current data to persistent storage. /// /// - Important: Call this method before the app enters background. /// /// - Warning: This operation may take several seconds for large datasets. /// /// - Tip: Use `saveInBackground()` for non-blocking saves. /// /// - Note: Data is automatically encrypted at rest. /// /// - Precondition: `isInitialized` must be `true`. func save() async throws ```

Symbol Links

Link to other symbols using double backticks:

```swift /// The data source for ``ContentView``. /// /// This view model works with ``PlaceRepository`` to fetch location data. /// See ``Place`` for the underlying data model. /// /// ## Topics /// /// ### Loading Data /// - ``loadPlaces()`` /// - ``refresh()`` /// /// ### State /// - ``places`` /// - ``isLoading`` @Observable class ContentViewModel { // ... } ```

For detailed documentation comment patterns, see references/documentation-comments.md.

DocC Catalog Structure

Creating a Catalog

Create a documentation catalog at `Sources/[Target]/Documentation.docc/`:

``` Sources/ └── handheld/ ├── Models/ ├── Views/ └── Documentation.docc/ ├── Documentation.md # Landing page (required) ├── GettingStarted.md # Article ├── Tutorials/ │ └── BuildingYourFirstRoute.tutorial └── Resources/ ├── hero-image.png └── tutorial-screenshot.png ```

Landing Page (Documentation.md)

```markdown

``handheld``

Plan and navigate sightseeing trips with ease.

Overview

handheld helps users discover nearby attractions, plan optimal routes, and navigate using Look Around preview.

Topics

Essentials

• doc:GettingStarted
• doc:Architecture

Models

• ``Place``
• ``Route``
• ``SightseeingPlan``

Services

• ``LocationManager``
• ``DirectionsService`` ```

For detailed catalog structure, see references/docc-catalog-structure.md.

Building Documentation

Xcode

1. Select Product → Build Documentation (⌃⇧⌘D)
2. Documentation opens in Developer Documentation window
3. Export: Product → Build Documentation Archive

Swift Package Manager

Add the DocC plugin to `Package.swift`:

```swift dependencies: [ .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0") ] ```

Generate documentation:

```bash

Generate static documentation

swift package generate-documentation --target handheld

Preview with local server

swift package --disable-sandbox preview-documentation --target handheld ```

XcodeGen

Add documentation catalog to `project.yml`:

```yaml targets: handheld: sources: - Sources/handheld - path: Sources/handheld/Documentation.docc type: folder ```

Hosting on GitHub Pages

Create `.github/workflows/documentation.yml`:

```yaml name: Documentation

on: push: branches: [main]

permissions: contents: read pages: write id-token: write

jobs: build: runs-on: macos-14 steps: - uses: actions/checkout@v4

  - name: Build Documentation
    run: |
      swift package --allow-writing-to-directory ./docs \\
        generate-documentation \\
        --target handheld \\
        --output-path ./docs \\
        --transform-for-static-hosting \\
        --hosting-base-path handheld

  - uses: actions/upload-pages-artifact@v3
    with:
      path: ./docs

deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - uses: actions/deploy-pages@v4 id: deployment ```

For detailed hosting setup, see references/hosting-deployment.md.

Best Practices

Additional Resources

Reference Files

• references/documentation-comments.md - Complete documentation comment syntax
• references/docc-catalog-structure.md - Catalog organization and directives
• references/articles-tutorials.md - Articles and tutorial creation
• references/hosting-deployment.md - CI/CD and hosting setup

Example Files

• examples/basic-documentation.swift - Documentation comment examples
• examples/Documentation.md - Landing page template
• examples/github-actions-docc.yml - CI/CD workflow

External Resources

• Apple: Writing Documentation
• swift-docc GitHub
• WWDC21: Elevate your DocC documentation