Use when writing or enhancing Swift documentation comments for DocC generation, adding inline doc comments to Swift source files, or when user asks for API documentation
81
87%
Does it follow best practices?
Impact
95%
1.00x2 of 3 eval scenarios. Add 1 more for a full score.
Passed
No findings from the security scan
Swift DocC inline comments follow a specific structure. Section headers like ## Overview and ## Topics belong in .docc catalog files, NOT in inline source comments.
/// Summary (first paragraph - one sentence)
///
/// Discussion paragraphs (no header needed)
///
/// ```swift
/// // Code example
/// ```
///
/// - Parameter name: Description
/// - Returns: Description
/// - Throws: Description
/// - Note: Additional info| Element | Format | Location |
|---|---|---|
| Summary | First paragraph | Inline |
| Discussion | Subsequent paragraphs | Inline |
| Code examples | Triple backticks | Inline, before parameters |
## Overview | Section header | .docc catalog ONLY |
## Topics | Section header | .docc catalog ONLY |
| Symbol links | ``SymbolName`` | Both |
/// Brief summary in one sentence.
///
/// Extended discussion explaining behavior, use cases,
/// or important details. No header needed.
///
/// ```swift
/// let example = MyType()
/// example.doSomething()
/// ```
///
/// - Parameter value: What this parameter does.
/// - Returns: What gets returned.
/// - Note: Default value is `.default`.
func method(value: Int) -> String| Wrong | Correct |
|---|---|
/// ## Overview | Just write paragraphs |
/// ## Topics | Use .docc catalog file |
/// ## Example | Just use code block |
| Parameters before code | Code block, then parameters |
These indicate wrong format:
## Overview in /// comments## Topics in /// comments## Example before code blocks- Parameter: appearing before code examplesswift package generate-documentationivan-magda/claude-superpowers
af7cba7
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.