name: objective-c-docstrings description: > document objective-c code with appledoc or jazzy-style comments so external tools can read the embedded api documentation. use when the request is to add, normalize, migrate, review, or explain objective-c source documentation, inline api help, or machine-readable comments.

Objective-C Docstrings

Use this skill to add or normalize AppleDoc or Jazzy-style comments in Objective-C code so external tools can discover API intent without reverse-engineering the implementation.

Intent Router

Quick Start

1. Inspect the repository for an existing documentation convention.
2. Preserve an established machine-readable style when it already works with external tooling.
3. Otherwise standardize on AppleDoc or Jazzy-style comments for the requested Objective-C surface.
4. Document public and externally consumed symbols before private helpers.
5. Keep names, parameters, return semantics, and examples aligned with the real code.

Workflow

• identify the externally consumed surface before adding comments or rewriting existing documentation
• add documentation directly adjacent to the declaration or symbol that external tools inspect
• prefer concise summaries first, then parameters, returns, exceptions, examples, or side effects when the format supports them
• mention or preserve the extraction path used by the surrounding toolchain
• keep migrations incremental when mixed styles already exist in a large file or module

Output Pattern

• state the convention being applied and why it matches the surrounding toolchain
• show declaration-adjacent documentation blocks rather than detached prose
• mention extraction or verification commands when they help confirm the result
• call out any symbols intentionally left undocumented because they are private or out of scope

Canonical Pattern

/**
 Add two integers.

 @param a Left operand.
 @param b Right operand.
 @return Sum of the operands.
 */
- (NSInteger)add:(NSInteger)a b:(NSInteger)b;

Extraction Path

jazzy --objc
Xcode Quick Help from header comments

Common Requests

Add or normalize Objective-C source documentation for this public API without changing behavior.

Review this Objective-C file for missing or misleading machine-readable documentation that external tools depend on.

Verification and Migration Checks

• verify the generated docs with the extraction path, metadata query, or generator named in references/docstrings.md
• compare parameter names, return values, exceptions, ownership notes, and examples against the real declaration after editing
• migrate one contiguous public surface at a time when a file mixes styles
• preserve an existing machine-readable convention when external tooling already depends on it, and state that choice explicitly

Recovery Cues

• if the repository already standardizes on another adjacent format, keep that format instead of forcing a conversion
• if a declaration is still unstable or private, document only the parts external tools or callers actually consume
• if behavior is unclear, reduce the prose to verified facts and mark open questions instead of inventing guarantees

Safety Notes

• do not invent behavior, preconditions, side effects, performance guarantees, or error modes that the code does not actually implement
• do not document private members unless the request, generator, or house style requires them
• do not mix competing documentation styles in the same file without a clear migration reason
• do not let examples drift away from the real API surface