swift-docc-pro

name	swift-docc-pro
description	Reviews and improves Swift documentation comments (DocC) for correctness, completeness, and clarity. Use when writing or reviewing public API documentation in Swift packages.
license	MIT
metadata	{"author":"Kelvin Kosbab","version":"1.0"}

Review Swift documentation comments for completeness, accuracy, and DocC compatibility. Report only genuine problems - do not nitpick or invent issues.

Review process:

1. Verify all public declarations have documentation comments using references/comment-syntax.md.
2. Validate parameter, return, and throws documentation completeness using references/comment-syntax.md.
3. Check symbol linking syntax (Type) using references/symbol-linking.md.
4. Validate code example formatting using references/code-examples.md.
5. Suggest ## Topics organization for types with many members using references/topics.md.

If doing a partial review, load only the relevant reference files.

Core Instructions

• All public declarations should have at least a one-line summary comment.
• Use triple-slash /// for declaration documentation, not /** */ block comments.
• Parameter, return, and throws documentation must match the actual signature exactly.
• Code examples in doc comments should be valid, compilable Swift.
• Use double-backtick symbol references (MyType) so DocC creates clickable links.
• Markdown links to external documentation are encouraged — link to Apple's docs whenever referencing system APIs.
• Don't repeat the obvious — public init() doesn't need "Initializes the type." Add docs only when they convey useful information.

Output Format

Organize findings by file. For each issue:

1. State the file and relevant line(s).
2. Name the rule being violated.
3. Show a brief before/after code fix.

Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.

Example output:

Sources/Retry/Retry.swift

Line 23: Missing - Throws: documentation for throwing function.

// Before
/// Retries an async operation with the configured strategy.
/// - Parameter operation: The async work to retry.
/// - Returns: The successful result of the operation.
public func retry<T>(
    _ operation: () async throws -> T
) async throws -> T

// After
/// Retries an async operation with the configured strategy.
/// - Parameter operation: The async work to retry.
/// - Returns: The successful result of the operation.
/// - Throws: The last error thrown by `operation` if all retry attempts are exhausted.
public func retry<T>(
    _ operation: () async throws -> T
) async throws -> T

Line 45: Use double-backtick to link to symbol instead of single backtick.

// Before
/// See `BackoffStrategy` for available strategies.

// After
/// See ``BackoffStrategy`` for available strategies.

Summary

1. Completeness (high): 4 throwing public functions in Sources/Retry/ are missing - Throws: documentation.
2. DocC linking (medium): Several symbol references use single backticks — change to double for proper linking.

End of example.

References

• references/comment-syntax.md — /// triple-slash syntax, - Parameter, - Returns, - Throws, - Note, - Warning.
• references/symbol-linking.md — Double-backtick symbol references, cross-module linking, member references.
• references/code-examples.md — Code blocks in doc comments, language hints, runnable examples.
• references/topics.md — ## Topics sections, grouping related symbols, top-level overviews.