Swift Documentation Quick Guide

Posted By Aditya Kumar Sharma | 16-May-2018

Documenting the code is a very important task for each and every developer. Although it makes the development process little bit slow. But for good developer, it's a required thing.

 

Xcode 7 introduced a powerful Markdown syntax for rich text formatting in the documentation. Let’s have a look at it:

 

Symbol Documentation

 

There are 4 sections, out of which description is always included in the documentation.

  1. Description
  2. Parameters
  3. Returns
  4. Throws

 

Description

 

To add any comment before a function, variable or a class. Just use triple-slash for single line comments. Or comment block with a slash and double asterisk for multiple lines. Eg:

/// Some introductory description for the method or the function
/// of the function.

/**
 What this function do?
 */

func someSoCalledFunction(name: String) -> Bool {
    return false
}
 

How it will appear in Quick-Help:

 

Parameters Section

 

Generally, all keyword starts with hyphen and end with the colon. We can document parameters with two ways either by using the parameter section or individual parameter fields. Eg:

/**
 Another description of useful function
 - parameters:
 - isAlpha: Describe the isAlpha param
 - isBeta: Describe the isBeta param
 */
func doSomething(isAlpha: Bool, isBeta: Bool) { }
 

How it will appear in Quick-Help:

/**
 Another description of useful function
 - parameter isAlpha: Describe the isAlpha param
 - parameter isBeta: Describe the isBeta param
 */
func doSomething1(isAlpha: Bool, isBeta: Bool) { }
 

How it will appear in Quick-Help:

 

Throws Section

 

If a function or method that contains throws section, it means it throws an error:

/// Some method which performs some work and
/// also throws error.
/// - Throws: SomeError you might want to catch

func someDemoFunction() throws -> Bool {
 

How it will appear in Quick-Help:

Returns section

 

If a function returns a value it contains return section:

/// Some method which performs some work and
/// also throws error.
/// - Returns: return value that you want to use
/// - Throws: SomeError you might want to catch

func someDemoFunction() throws -> Bool {
    return true
}
 

How it will appear in Quick-Help:

Other Keywords

 

There is a long list of the keyword, some of them are:

/**
 Other **Keywords** available for documentation
 
 - Attention: Watch out for this!
 - Author: Aditya Sharma
 - Authors:
    Aditya Sharma1
    Aditya Sharma2
 - Bug: crashing for alphanumeric case
 - Complexity: O(log n^2) approx
 - Copyright: 2018 Copyright
 - Date: Jan 1, 2018
 - experiment: have a try
 - important: know this
 - invariant: something
 - Note: foo foo foo
 - Precondition: value should not be nil
 - Postcondition: Result successful
 - Remark: something else
 - Requires: iOS 11, xCode 9
 - seealso: something else
 - Since: iOS 11
 - Todo: Need to complete it
 - Version: 1.0.2
 - Warning: Deprecated
 */
 

 

Have a happy documenting to all! 

Request for Proposal

Recaptcha is required.

Sending message..