Now that I’ve gotten Swift 2 to 3 ready and out, I’ve turned my attention to Swift Documentation Markup. I’m updating the book with both Swift 3 examples and markup enhancements. Xcode has added some great new features although as you’ll see there’s still work left to be done.
Xcode’s automatic doc-comment skeleton command is super handy. Move the cursor to any symbol and select Editor > Structure > Add Documentation (Command-Option-/). Xcode scans the symbol you’ve chosen and adds a doc-comment outline including named parameters and return types if they exist.
You may want to add further comment features like notes, warnings, authorship, dates, and complexity details, but the basics provided by Xcode form a great place to get started.
One Xcode feature that’s just launching is support for treating closure parameters as first-class documentation elements. Xcode’s default documentation doesn’t include closure parameters, as you see in the screenshot that follows.
Swift’s new “no labels for function types” means that many developers will not include the internal declaration arguments that I use in this example for the action parameter.
By adding internal arguments like (_ line: String), you can extend your documentation. Xcode picks up and formats that information into a special closure parameter box, subordinate to the closure that uses that parameter. Here’s an example that extends the code documentation you just saw:
Swift’s native comment schema suggests that Xcode could potentially add further support. The schema includes nesting parameters, return values, and throws document comments, as promised in this commit:
As far as I can tell, the only feature that is currently supported by Xcode is the named closure parameters, demonstrated above. Here’s what the schema looks like from Swift’s point of view:
<!-- In general, template parameters with whitespace
discussion should not be emitted, unless direction
is explicitly specified. Schema might be more strict here. -->
<choice>
<element name="ClosureParameter">
<optional>
<ref name="Abstract" />
</optional>
<optional>
<ref name="Parameters" />
</optional>
<optional>
<ref name="ResultDiscussion" />
</optional>
<optional>
<ref name="ThrowsDiscussion" />
</optional>
<optional>
<ref name="Discussion" />
</optional>
</element>
<element name="Discussion">
<ref name="BlockContent" />
</element>
</choice>
Unadopted Swift enhancements don’t end there. There’s further work to be done to support changes provided by Swift but not picked up on by Xcode. Here are examples from the Swift language change log and from Swift proposal SE-0111:
- Three new doc comment fields, namely
- keyword:, - recommended: and - recommendedover:, allow Swift users to cooperate with code completion engine to deliver more effective code completion results. The - keyword: field specifies concepts that are not fully manifested in declaration names. - recommended: indicates other declarations are preferred to the one decorated; to the contrary, - recommendedover: indicates the decorated declaration is preferred to those declarations whose names are specified.
- This proposal introduces two new document comment fields,
MutatingCounterpart and NonmutatingCounterpart. These replace the roles of the former mutable_variant and message arguments. Under this scheme, @discardableResultwill not use arguments. Documentation comment fields will, instead, supply usage recommendations in both directions.
