Swift Documentation

Any code of your own that you haven't looked at for six or more months might as well have been written by someone else.

– Eagleson's Law

When we work with Apple's class and not sure how to use it, we have many ways to find out that information. You can find it in an online document like Apple Developer Documentation or you can find in within Xcode.

It comes in many shapes and forms.

Quick help popover #

You can ⌥ – Option + click on any class to open up quick help like this:

Quick help of UIButton

Symbol inspector Quick Help #

Quick help also shows under the Quick Help inspector panel.

Quick help of UIButton

Code completion hint #

When you start typing, Xcode will help you by suggesting a list of a function/property/enum of that class, along with a hint of what they do at the very bottom.

Short summary of a function showing up in auto-complete

Short summary of a property showing up in auto-complete

Short summary of an enum showing up in auto-complete

Do you know that we can have these comments for our code too? This article will tell you how.

Writing documentation for your code is like writing a comment, but with a small syntax change. You need an extra slash for single-line documentation, so instead of two, you need three slashes (///).



struct User {

let firstName : String

let lastName : String

}

For multi-line documentation, you need extra asterisk (*) in the opening delimiter (/** ... */).



struct User {

let firstName : String

let lastName : String

}

Summary and Discussion #

The above documentation comment will produce a document with a summary part.

The first paragraph will be used as a documentation summary.

To add a discussion section, what you need to do is write another paragraph. Anything other than the first paragraph will belong in the discussion section.

Documentation comments in Swift use Markdown-flavored markup syntax. So when we refer to the paragraph in the document, we mean the paragraph in markdown way. A paragraph in markdown is one or more consecutive lines of text separated by one or more blank lines.

So the example above is a paragraph with two sentences. Which makes them belong in the summary section.

If you want the second sentence in the discussion section, make it into another paragraph by adding a new line between those sentences.

You can also use standard markdown in your documentation.



struct User {

let firstName : String

let lastName : String

}

The above example is valid documentation, which will produce the following quick help.

The first paragraph of a documentation comment becomes the documentation Summary. Any additional content is grouped into the Discussion section.

Summary and discussion would be enough for documenting a class, property, or simple function. For a complex function, we have a few more sections that we can add.

For a function with parameters, you can add the parameter section to Quick Help. There are two methods of documenting parameters. A Parameters Section and separate Parameter Fields.

Separate Parameter Fields #

- Parameter x : . . .

- Parameter y : . . .

Parameters Section #

This declaration style suit for function with many parameters. Using separate Parameter Fields might be a bit repetitive if you have many parameters.

- Parameters :

- x : . . .

- y : . . .

- z : . . .

For a function with a return value, you can add the return section, like the one you did with parameters.

- Returns : . . .

You may specify multiple Returns items at the top level, but only the last one will be shown in Xcode's QuickHelp.

The last and the most important one. Since you can't specify error type that will be throw when you declare a function with throws keyword, it is handy to have this information sit right next to that function.

- Throws : . . .

Functions that are marked as Throws should contain the following describing what kind of errors are thrown and in what situations.























func greeting ( person : User ) throws - > String {

return "Hello \( person . firstName ) \( person . lastName ) "

}

Throws section

There can be only one Throws delimiter in the comments for a symbol. The behavior for multiple Throws delimiters is undefined.

Auto-generate Quick Help documentation #

Xcode provides an easy way to generate documentation. To use this feature, click on any class, property, function, or part you want to add a document. Then press ⌥ – Option + ⌘ - command + / or Editor > Structure > Add documentation from Xcode's menu. Xcode will generate a document template for you.





This feature can vary based on your Xcode version. From what I remembered, it used to generate parameters, returns, and throws of the current function, but in Xcode Version 11.1 (11A1027) it only generates parameters.

Extra Fields #

There are many more Callout that you can add to the documentation. You add Callout with the following syntax:

- Callout : description

Following are all Callout that you can use:

- Attention : . . .

- Author : . . .

- Authors : . . .

- Bug : . . .

- Complexity : . . .

- Copyright : . . .

- Date : . . .

- Experiment : . . .

- Important : . . .

- Invariant : . . .

- Note : . . .

- Postcondition : . . .

- Precondition : . . .

- Remark : . . .

- Remarks : . . .

- Requires : . . .

- See : . . .

- Since : . . .

- Todo : . . .

- Version : . . .

- Warning : . . .

The Callout will render in Quick Help under the discussion section as a bold header followed by a block of text.

Here is an example of our User documentation with Warning callout.













func greeting ( person : User ) - > String {

return "Hello \( person . firstName ) \( person . lastName ) "

}

Warning Callout

It is only a matter of time before your code that once obvious, turns into someone else code. We all know it is not easy and quite a time-consuming task to come up with a good document, but having good documentation will pay off in the long run.

Related Resources #

Feel free to follow me on Twitter and ask your questions related to this post. Thanks for reading and see you next time.

If you enjoy my writing, please check out my Patreon https://www.patreon.com/sarunw and become my supporter. Sharing the article is also greatly appreciated.

Become a patron

Tweet

Share

← Home