Making code documentation

Here is a cheat sheet

Swift Documentation Comments

// MARK: - heading
// TODO: comment
// FIXME: comment

Block and single line comments

/**
 *

 */

Or

///
///
///

Example:

/// One line description of function.
///
///
A detailed description
/// may be placed on the remaining lines
/// - parameter something: the parameter description
///
- throws: `ErrorCode.noDevicePersister` The `something` parameter was blank.
///
- returns: a result of the computation
func think(about
something: String) throws -> String {   

Longer parameter lists:

/// - Parameters:
///     - x: The *x* component of the vector.
///     - y: The *y* component of the vector.
///     - z: The *z* component of the vector.
func magnitude3D(x: Double, y: Double, z: Double) -> Double {

Description fields headers

Algorithm/Safety Information: Precondition, Postcondition, Requires, Invariant, Complexity, Important, Warning

Metadata: Author, Authors, Copyright, Date, SeeAlso, Since, Version

General Notes & Exhortations: Attention, Bug, Experiment, Note, Remark, ToDo

Code blocks

Indent code block by at least 4 spaces.

/**
    The area of the `Shape` instance.

    Computation depends on the shape of the instance. 
    For a triangle, `area` will be equivalent to:

        let height = triangle.calculateHeight()
        let area = triangle.base * height / 2
*/

Fence unindented code blocks using triple backtick (```) or tilde (~):

```
// Circles:
let perimeter = circle.radius * 2 * CGFloat(M_PI)

// Other shapes:
let perimeter = shape.sides.map { $0.length }
                           .reduce(0, combine: +)
```

For further reading: