Swift functions: documentation comments

Goal

Learn how to document Swift functions using Apple's documentation comment style. Use documentation comments that show up in Quick Help and DocC. Practice writing clear summaries, parameters, and returns.

/// Calculates the floor area of a room.
/// - Parameters:
///   - length: The room length in metres.
///   - width: The room width in metres.
/// - Returns: The area in square metres.
func roomArea(length: Double, width: Double) -> Double {
    return length * width
}

What is function documentation?

Function documentation is text placed in special comments above a function. Apple's tooling reads these comments to show Quick Help and DocC pages. The comments use Markdown-style formatting as described in Apple's markup reference.

See Apple's documentation on writing symbol documentation.

/// Prints a divider line for output sections.
func printDivider() {
    print("--------")
}

Why developers use documentation comments

They help other developers understand intent without reading all the code. They make code completion and Quick Help more useful. They reduce mistakes when using functions with many parameters.

/// Converts a volume in cubic metres into litres.
/// - Parameter cubicMetres: The volume in m³.
/// - Returns: The volume in litres.
func litres(from cubicMetres: Double) -> Double {
    return cubicMetres * 1000
}

Example of Apple's documentation style

Apple's style uses a short summary sentence followed by structured fields. Use the - Parameters: list for multiple parameters. Use - Returns: for the return value.

Reference: Parameters in markup.

/// Calculates paint needed for a wall.
/// - Parameters:
///   - area: The wall area in m².
///   - coverage: The coverage per litre.
/// - Returns: Litres of paint required.
func paintNeeded(area: Double, coverage: Double) -> Double {
    return area / coverage
}

Anatomy of a documentation comment

Start with a summary line that reads like a sentence. List parameters and describe each one. Include a returns line when the function returns a value.

Reference: Adding markup.

/// Checks if a room is small.
/// - Parameter volume: The room volume in m³.
/// - Returns: True if the room is below 60 m³.
func isRoomSmall(volume: Double) -> Bool {
    return volume < 60
}

How to write clear documentation

Use verbs that describe the function's action. Describe units or expectations for each parameter. Keep sentences short and specific.

/// Formats a number as a money string.
/// - Parameter value: The amount in dollars.
/// - Returns: A formatted string like "$6.50".
func money(_ value: Double) -> String {
    return "$" + String(format: "%.2f", value)
}

How to use documentation in your code

Write documentation comments directly above the function declaration. Use triple slashes /// or a block comment /** */. Preview Quick Help in Xcode to check formatting.

/**
 Adds the two values together.
 - Parameters:
   - a: The first value.
   - b: The second value.
 - Returns: The total of a and b.
 */
func add(_ a: Int, _ b: Int) -> Int {
    return a + b
}

How documentation contributes to flexibility

Clear docs make it easier to reuse functions in new projects. They allow teammates to use your API without asking questions. They reduce errors when parameters are similar or easy to confuse.

/// Converts metres to millimetres.
/// - Parameter metres: The length in metres.
/// - Returns: The length in millimetres.
func millimetres(from metres: Double) -> Double {
    return metres * 1000
}

How to test documentation output

Open Quick Help in Xcode to confirm the summary and fields. Check that parameter names appear in the correct order. Fix any formatting issues in your comment text.

Reference: Markup overview.

/// Prints a labelled result line.
/// - Parameters:
///   - label: The label to show.
///   - value: The numeric value to print.
func printResult(label: String, value: Double) {
    print("\(label): \(value)")
}

Task A

func roomArea(length: Double, width: Double) -> Double {
    return length * width
}

Task B

func roomVolume(length: Double, width: Double, height: Double) -> Double {
    return length * width * height
}

Task C

func isRoomSmall(volume: Double) -> Bool {
    return volume < 60
}

Task D

func reducedHeight(original: Double, reductionPercent: Double) -> Double {
    let multiplier = (100.0 - reductionPercent) / 100.0
    return original * multiplier
}