# 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

- Skill: `tomevault-io/swift-docc-comments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/swift-docc-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/swift-docc-comments/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/swift-docc-comments

---


# 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

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

```bash
swift package generate-documentation
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ivan-magda) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->