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

KeywordWhat’s for?
AuthorAuthor of the code
AuthorsAuthors of the code
CopyrightCopyright information
DateCode date
RequiresSomething that is required
SinceAdd availability information
VersionCode version
ComplexityAlgorithmic complexity
ExperimentProvide examples to experiment with
InvariantDisplay a condition that will be true during the execution
PreconditionConditions to have in mind
PostconditionConditions which have guaranteed values upon completion
AttentionHighlight information
BugReport bug
ImportantHighlight information that can have adverse effects
RemarkSomething to highlight
WarningAdd warnings
NoteAdd 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

Leave a Reply

Your email address will not be published. Required fields are marked *