Swift header documentation in Xcode 7

Update: There’s now a book!

cover

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
*/

Screen Shot 2015-06-14 at 2.53.10 PM

Markdown Support

Quick Help supports basic markdown syntax. For example, you can add headers, links, horizontal rules, bolding, and italics to your core description.

Screen Shot 2015-06-14 at 2.51.12 PM

You can also add code insets. Use the “`swift code fence or add four spaces or more to indicate code sections.

Screen Shot 2015-06-14 at 3.11.46 PM

Keywords

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)

Screen Shot 2015-06-14 at 3.00.43 PM

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.

Screen Shot 2015-06-14 at 3.08.52 PM

You can use the same hyphen space colon layout for other items but they don’t receive preferred markup.

Screen Shot 2015-06-14 at 3.21.20 PM

  • 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.

Screen Shot 2015-06-14 at 3.24.53 PM

and

Screen Shot 2015-06-14 at 3.32.11 PM

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)

Screen Shot 2015-07-27 at 1.35.27 PM

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:

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.

Screen Shot 2015-06-15 at 2.07.59 PM

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.

@Finally.

RIP reStructuredText

4 Comments

Join the Discussion

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>