Missing Docs

ID

swift.missing_docs

Severity

info

Remediation Complexity

auto_fix

Remediation Risk

low

Remediation Effort

low

Resource

Documentation

Language

Swift

Tags

documentation, public_api

Description

Reports a public or open declaration that is not preceded by a /// doc comment. Public API is the contract a library exposes to consumers; without quick-help text Xcode shows only the bare signature, and external readers have to guess at preconditions, side effects, and the meaning of each parameter.

public func render() { }            // FLAW — no /// doc

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

Rationale

A doc comment is the lightweight contract for a public symbol. It shows up in Xcode quick-help, in generated DocC sites, and on hover in any IDE — the same text serves every consumer. The cost of writing one line is small; the cost of an undocumented public API is silent confusion at every call site downstream.

Remediation

Add a /// doc comment that explains what the symbol does (not how — that’s already in the implementation):

/// Returns a localized representation of `value`, falling back to
/// the en-US locale when `Locale.current` is undefined.
public func localized(_ value: Int) -> String { ... }

When not to fire

The rule is meant for framework / SDK authors and is silent on internal application code:

  • fires only on declarations with an explicit public or open access level;

  • applies to top-level declarations and to direct members of type declarations;

  • protocol member <em>requirements</em> are skipped — those inherit the protocol’s own documentation.

internal, private, fileprivate declarations are never flagged.

References