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
}