Document your functions

Did you know that pressing ⌥ + ⌘ + / in any function declaration displays an auto-generated document template for that function?

You can also add extra lines to that template using Swift’s version of Markdown, which is an extremely useful tool to document our code, for the sake of us, the future us and whoever run into our code.

Easy peasy shortcut

Let’s asume we have this function:

func sumTwoIntegers(number1: Int, number2: Int) -> Int {
    return number1 + number2
}

By pressing ⌥ + ⌘ + / with the cursor placed in any portion of the function declaration, we get an auto-generated document template for that function:

/// <#Description#>
/// - Parameters:
///   - number1: <#number1 description#>
///   - number2: <#number2 description#>
func sumTwoIntegers(number1: Int, number2: Int) -> Int {
    return number1 + number2
}

Which will look like this:

Now you can fill in the blanks and have a proper description of your function.

Now what?

Obviously you want to see how your documentation looks like. You basically have two different places where you’ll see your comments.

Quick Help Inspector

You’ll find this well-known section at your right panel, by pressing ⌥ + ⌘ + 3 (shortcut for View > Inspectors > Show Quick Help Inspector). In this inspector you may see the function’s documentation once you put your cursor over its name (whether its declaration or when calling it):

Quick Help

While holding ⌥, hover your function and click after you see an interrogation mark symbol (or right-click > Show Quick Help). You will see something like this:

But there’s more…

Swift’s Markdown version lets you add more details to your comments.

Parameters

By default you get a template to add your parameters’ description. But it may happen you add new parameters to your function or want to create the whole comment on your own. So you can add new parameters as follows:

/// - Parameters:
///   - {parameter name}: {description}

For example:

/// - Parameters:
///   - number1: first number you want to add
///   - number2: second number you want to add

Returns

Most functions will return something and you should document that as well. This is how it goes:

/// - Returns: {description}

For example:

/// - Returns: The sum of number1 and number2

Throws

Many functions will throw an error you should catch at some point. You got a magic word for that too:

/// - Throws: {description}

Metadata

You can easily add metadata to your functions description. These are keywords that are listed inside a Discussion section within the quick help with the value you set up. The structure is the same for everyone:

/// - {keyword}: {description}

For example:

/// - Author: Leandro Fournier

Keywords

Keyword	What’s for?
Author	Author of the code
Authors	Authors of the code
Copyright	Copyright information
Date	Code date
Requires	Something that is required
Since	Add availability information
Version	Code version
Complexity	Algorithmic complexity
Experiment	Provide examples to experiment with
Invariant	Display a condition that will be true during the execution
Precondition	Conditions to have in mind
Postcondition	Conditions which have guaranteed values upon completion
Attention	Highlight information
Bug	Report bug
Important	Highlight information that can have adverse effects
Remark	Something to highlight
Warning	Add warnings
Note	Add a note

What now?

You can embellish your documentation by following these tips!

Start documenting your code EASILY with this shortcut! #swift #documenting #markdown #ios

Tweet