| name | swift-docc |
| description | This skill should be used when the user asks to "create DocC documentation",
"add documentation comments", "write API docs", "set up DocC catalog",
"host documentation on GitHub Pages", "document Swift code", "write /// comments",
"create tutorials", "generate documentation", "build documentation",
"DocC を作成", "ドキュメントコメントを追加", "API ドキュメントを書く",
"DocC カタログを設定", "GitHub Pages でホスト", "Swift コードをドキュメント化",
"/// コメントを書く", "チュートリアルを作成", "ドキュメントを生成",
or needs guidance on DocC catalogs, documentation comments,
symbol documentation, articles, tutorials, or documentation hosting
for iOS 17+/macOS 14+ Swift projects.
|
| version | 0.1.0 |
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
Example Files
External Resources
