[转] http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/
Basic Header Documentation
A Quick Help comment consists of a either triple line or double-asterisked comments:
Markdown Support
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.
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.
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.
and
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.
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:
.@ericasadun RE: http://t.co/11w5MAIC1J I saw mentions and demos of images in comments, do you know how to get them working?
— 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.
@Finally.
RIP reStructuredText
参考：