Orphaned Doc Comment

ID

swift.orphaned_doc_comment

Severity

low

Remediation Complexity

trivial

Remediation Risk

low

Remediation Effort

low

Resource

Reliability

Language

Swift

Tags

documentation, reliability

Description

Reports a /// or /** …​ */ doc-comment block that is not immediately followed by a declaration. Xcode’s quick-help associates a doc comment with the next declaration only when they are adjacent; a blank line, a regular // comment, or any code between the doc and the declaration breaks the association, so the documentation never shows up in tooling.

/// Renders the row.            // FLAW — followed by a blank line

func render() { }

/// Renders the row.            // OK — attached
func render() { }

Rationale

Doc comments are part of the public contract — Xcode, Jazzy, and DocC all read them. A misplaced doc looks present in source but is silently dropped by the documentation pipeline, and consumers see no quick-help on hover. The fix is mechanical (remove the blank line) but the only way to notice the gap is to read the generated docs.

Remediation

Move the doc comment so it sits directly above the declaration:

/// Renders the row.
func render() { }

If the doc is intentionally above a section of code (not a single declaration), use // MARK: - for IDE outlining instead — that’s the right tool, and it does not promise quick-help attachment.

When not to fire

  • Doc comments followed by a declaration line (including ones that start with an attribute like @available or with an access-level modifier) are considered attached.

  • Multiple consecutive /// lines are treated as a single doc block.

References