Documentation markup

Class documentation

Here is a basic class documentation example:

/// Class description
class Student {

    // Member description
    var name: String
    
    /// Method description
    ///
    /// - parameter content:   parameter description
    ///
    /// - returns: return value description
    func say(content: String) -> Bool {
        print("\(self.name) say \(content)")
        return true
    }
}

Note that with Xcode 8, you can generate the documentation snippet with command+option+/.

This will return: (opens new window)

Documentation styles

/**
 Adds user to the list of poople which are assigned the tasks.
 
 - Parameter name: The name to add
 - Returns: A boolean value (true/false) to tell if user is added successfully to the people list.
*/
func addMeToList(name: String) -> Bool {
    
    // Do something....
    
    
    return true
}

(opens new window)

/// This is a single line comment
func singleLineComment() {
    
}

(opens new window)

/**
 Repeats a string `times` times.
 
 - Parameter str:   The string to repeat.
 - Parameter times: The number of times to repeat `str`.
 
 - Throws: `MyError.InvalidTimes` if the `times` parameter
 is less than zero.
 
 - Returns: A new string with `str` repeated `times` times.
*/
func repeatString(str: String, times: Int) throws -> String {
    guard times >= 0 else { throw MyError.invalidTimes }
    return "Hello, world"
}

(opens new window)

/**
 # Lists
 
 You can apply *italic*, **bold**, or `code` inline styles.
 
 ## Unordered Lists
 - Lists are great,
 - but perhaps don't nest
 - Sub-list formatting
 - isn't the best.
 
 ## Ordered Lists
 1. Ordered lists, too
 2. for things that are sorted;
 3. Arabic numerals
 4. are the only kind supported.
*/
func complexDocumentation() {
    
}

(opens new window)

/**
 Frame and construction style.
 
 - Road: For streets or trails.
 - Touring: For long journeys.
 - Cruiser: For casual trips around town.
 - Hybrid: For general-purpose transportation.
*/
enum Style {
    case Road, Touring, Cruiser, Hybrid
}

(opens new window)