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
- Add documentation comments to public APIs using `///`
- Create DocC catalog at `Sources/[Target]/Documentation.docc/`
- Build documentation: Product → Build Documentation (⌃⇧⌘D)
- 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
Models
- ``Place``
- ``Route``
- ``SightseeingPlan``
Services
- ``LocationManager``
- ``DirectionsService`` ```
For detailed catalog structure, see references/docc-catalog-structure.md.
Building Documentation
Xcode
- Select Product → Build Documentation (⌃⇧⌘D)
- Documentation opens in Developer Documentation window
- 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
| Practice | Description | |----------|-------------| | Document public APIs | All `public` and `open` symbols should have documentation | | Use examples | Include code examples for complex APIs | | Explain "why" | Document the purpose, not just the behavior | | Keep it current | Update docs when code changes | | Use callouts | Highlight important information with Note, Warning, etc. |
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