Update: There’s now a book!
Quick Help offers concise in-line reference docs for symbols, build settings, and interface objects. Want to check a symbol’s type? Quick Help it. Need to look up parameters? Quick Help to the rescue. Add Quick Help to annotate your code and create custom information that displays via pop-ups (option-click symbols) and the Quick Help inspector (View > Utilities > Show Quick Help Inspector).
Update: Like this write-up? Read the book. It offers greatly expanded examples, discussions, details, best practices, etc.
Basic Header Documentation
A Quick Help comment consists of a either triple line or double-asterisked comments:
/// This is a quick help comment /** And so is this */
Quick Help supports basic markdown syntax. For example, you can add headers, links, horizontal rules, bolding, and italics to your core description.
You can also add code insets. Use the “`swift code fence or add four spaces or more to indicate code sections.
Quick Help supports parameter, returns, and Throws keywords that create category call-outs in the pop-up. These keywords are case insensitive. Returns requires its colon. The colon for parameter is optional but creates a more-readable tab-aligned list of parameters.
- returns: term - parameter term:definition - Throws: error lists (Introduced in Xcode 7 beta 4, see below)
Quick Help recognizes several other keywords and uses bolding to highlight them. These are: Attention, Author, Authors, Bug, Complexity, Copyright, Date, Experiment, Important, Invariant, Note, Postcondition, Precondition, Remark, Requires, See, SeeAlso, Since, TODO, Version, Warning.
You can use the same hyphen space colon layout for other items but they don’t receive preferred markup.
- Attributions (author, authors, copyright, date) create a documentation trail for authorship.
- Availability (since, version) specifies when material was added to the code or updated, enabling you to lock down both release conformance and real-world time.
- Admonitions (attention, important, note, remark, warning) caution about use. These establish design rationales and point out limitations and hazards.
- Development State (bug, TODO, experiment) express progress of ongoing development, marking out areas needing future inspection and refinement.
- Implementation qualities (complexity) express a code’s time and space complexity.
- Functional Semantics (precondition, postcondition, requires, invariant) detail predicates about argument values before and after calls. Preconditions and requirements limit the values and conditions under which the code should be accessed. Postconditions specify observable results that are true after execution.
- Cross Reference (see) enables you to point out related material to add background to the documented implementation.
Special Swift Concerns
Method / function annotation appears in-line with the declaration, for example, when a function throws.
Update (beta 4): “Swift documentation comments recognize a top-level list item – Throws: … which should be used to document what errors can be thrown and why. These appear alongside parameters and return descriptions in Xcode’s QuickHelp. (21621679)”
Unfortunately, you cannot break out the errors into lists the way you do with parameters. This fails to parse and you end up with one of the two being eaten by Xcode.
/// - Throws: Error.failure: Could not complete request /// - Throws: Error.cranky: Bad day for Xcode
For now, just list your errors as freeform text and file radars.
Adding Images to Header Docs
Yes, Virginia, you can add images. Chris Wagner writes:
— Chris Wagner (@cwagdev) June 15, 2015
You can if you use URLs not tied to the local file system of the running playground app. Rich document support sees the “sub.jpg” file in the following example (click for a larger version). Header docs cannot.
The “sub.jpg” image is stored with respect to the local app. That’s fine for playground markup. It knows to find a copy of the Resources file at the top level of the running iOS playground app. Header docs cannot read in-app resources but it can from a full path to my desktop. The ban.jpg file is freely accessible to both rich text docs and header docs through the external URL and renders as requested.