DocC Documentation
Write documentation that builds correctly and follows Apple's DocC conventions.
Quick Reference
Documentation Comment Syntax
swift
/// Summary sentence (becomes the abstract). /// /// Discussion paragraph with additional context. /// Can span multiple lines. /// /// - Parameters: /// - name: Description of the parameter. /// - value: Another parameter description. /// - Returns: What the function returns. /// - Throws: ``ErrorType`` when something fails. /// /// ## Example /// ```swift /// let result = myFunction(name: "test", value: 42) /// ``` func myFunction(name: String, value: Int) throws -> String
Symbol Linking
| Syntax | Use |
|---|---|
TypeName | Link to type |
TypeName/method | Link to member |
<doc:ArticleName> | Link to article |
Documentation Catalog Structure
code
ModuleName/
├── Sources/
│ └── *.swift
└── Documentation.docc/
├── Main.md # Landing page (# ``ModuleName``)
├── Article.md # Conceptual articles
└── Resources/
├── image@2x.png # Light mode
└── image~dark@2x.png # Dark mode
Main.md Template
markdown
# ``ModuleName`` One-sentence summary of the module. ## Overview Paragraph explaining the module's purpose and key concepts. ## Topics ### Group Name - ``TypeName`` - ``TypeName/property`` - <doc:ArticleName>
Article Template
markdown
# Article Title Summary sentence for the article. ## Overview Introductory paragraph. ## Section Header Content with code examples: ```swift // Example code
code
## Layout Directives
For rich layouts beyond standard Markdown:
```markdown
@Row {
@Column {
Paragraph text explaining a concept.
}
@Column {
}
}
@TabNavigator {
@Tab("First") {
Content for first tab.
}
@Tab("Second") {
Content for second tab.
}
}
Common Issues
| Problem | Solution |
|---|---|
| Symbol not found | Verify symbol is public; use full path Module/Type/member |
| Image not showing | Check file is in Documentation.docc, correct naming (@2x, ~dark) |
| Article not linked | Add <doc:ArticleName> to Topics section in Main.md |
| Build warning "No overview" | Add ## Overview section after title |
Validation
Build documentation to check for errors:
bash
# In Xcode: Product → Build Documentation # Or via command line: xcodebuild docbuild -scheme SchemeName