swift-docc-comments

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

1.00x

Quality

—

Does it follow best practices?

Impact

95%

1.00x

Average score across 2 eval scenarios

Securityby

Passed

No known issues

Swift DocC Inline Comments

Overview

Swift DocC inline comments follow a specific structure. Section headers like ## Overview and ## Topics belong in .docc catalog files, NOT in inline source comments.

Structure

/// Summary (first paragraph - one sentence)
///
/// Discussion paragraphs (no header needed)
///
/// ```swift
/// // Code example
/// ```
///
/// - Parameter name: Description
/// - Returns: Description
/// - Throws: Description
/// - Note: Additional info

Quick Reference

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

Correct Format

/// 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

Common Mistakes

Wrong	Correct
`/// ## Overview`	Just write paragraphs
`/// ## Topics`	Use `.docc` catalog file
`/// ## Example`	Just use code block
Parameters before code	Code block, then parameters

Red Flags

These indicate wrong format:

## Overview in /// comments
## Topics in /// comments
## Example before code blocks
- Parameter: appearing before code examples

Generate Documentation

swift package generate-documentation

Repository: ivan-magda/claude-superpowers
Commit: af7cba7

Last updated: 6 days ago
Created: 6 days ago

Is this your skill?

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.