2017年5月15日 | Leave a comment [转] 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: /// This is a quick help comment /** And so is this */ 12345 /// This is a quick help comment /** And so is this*/ 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. - returns: term - parameter term:definition - Throws: error lists <em>(Introduced in Xcode 7 beta 4, see below)</em> 123 - returns: term - parameter term:definition- Throws: error lists <em>(Introduced in Xcode 7 beta 4, see below)</em> 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. /// - Throws: Error.failure: Could not complete request /// - Throws: Error.cranky: Bad day for Xcode 12 /// - 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: .@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 参考: Swift header documentation in Xcode 7