Adding markups and documentation to Swift in Xcode | SwiftUI Bootcamp #45

Well-documented code doesn't just help your teammates — it helps your future self. Swift's documentation markup system feeds directly into Xcode's Quick Help popup (Option+Click) and generates rich developer documentation. After this lesson you'll know how to use // MARK: sections to navigate large files, write /// doc comments with parameters and warnings, and structure a view with clear delimiters.

What You'll Learn

• How to use // MARK: comments to create named sections that appear in Xcode's Jump Bar
• How to write triple-slash /// documentation comments that populate Xcode's Quick Help panel
• How - Parameter, - Returns, - Warning, and fenced code blocks work inside doc comments
• How // MARK: - differs from // MARK: (with vs. without a separator line) for visual organization

Mental Model

Imagine your Swift file is a physical binder with dividers. // MARK: PROPERTIES is a colored tab divider labeled "Properties" — when you click the file's Jump Bar at the top of Xcode's editor, every MARK comment appears as a divider in the dropdown, letting you jump directly to that section. The file's structure becomes self-documenting in the editor.

/// doc comments are like sticky notes on each function that appear in a formatted popup whenever someone Option+Clicks the function name — anywhere in the codebase. They explain what the function does, what each parameter means, what it returns, and what can go wrong. This is the same format Apple uses for its own SDK documentation, so your internal APIs feel just as polished.

Detailed Explanation

Swift supports two styles of in-code documentation. Single-line // comments and multi-line /* block comments */ are plain annotations that only appear in the source file. Triple-slash /// doc comments are parsed by Swift's documentation engine (DocC) and shown by Xcode as rich Quick Help content. The difference is immediately visible: hold Option and click any documented function or property — /// comments render as formatted documentation; // comments do not appear at all.

// MARK: comments are processed by Xcode's editor, not the Swift compiler. They create named sections visible in the Jump Bar (the breadcrumb bar at the top of the editor). // MARK: - adds a horizontal separator line above the section name in the dropdown, which helps visually separate major groups. This is especially valuable in large view files where PROPERTIES, BODY, COMPONENTS, FUNCTIONS, and PREVIEWS are logically distinct.

Within a /// doc comment you can use special field markers: - Parameter name: description documents an argument, - Returns: description documents the return value, - Warning: message shows a yellow warning badge in Quick Help, and triple-backtick code blocks render as formatted inline code examples. These follow the same syntax as DocC, so they work seamlessly with xcodebuild docbuild if you later want to generate a documentation archive.

Use documentation comments for any function that is reused more than once, any function with parameters that aren't self-explanatory, and any function that has side effects or preconditions. Avoid over-documenting trivial one-liners — /// Gets the title above var title: String adds noise without value. The goal is to communicate what someone can't figure out by reading the function signature alone.

Code Structure

DocumentationBootcamp.swift is a complete example of a well-structured, documented SwiftUI view. It uses // MARK: to divide the file into Properties, Body, and Functions sections. The foregroundLayer computed property has a /// comment. The getAlert function has a full doc comment with a parameter, return value, warning, and code example — exactly the level of detail you'd want on a shared utility function.

Complete Code

DocumentationBootcamp.swift

import SwiftUI

struct DocumentationBootcamp: View {
    
    // MARK: PROPERTIES
    // "MARK:" creates a named section visible in Xcode's Jump Bar dropdown
    
    @State var data: [String] = [
        "Apples", "Oranges", "Bananas"
    ]
    @State var showAlert: Bool = false
    
    // MARK: BODY
        
    // NICK - Working copy - things to do:
    /*
     1) Fix title
     2) Fix alert
     */
    // multi-line block comment used for quick dev notes; not shown in Quick Help
    
    var body: some View {
        NavigationView { // START: NAV
            ZStack {
                // background
                Color.red.ignoresSafeArea()
                
                // foreground
                foregroundLayer
                .navigationTitle("Documentation")
                .navigationBarItems(trailing:
                                        Button("ALERT", action: {
                                            showAlert.toggle()
                                        })
                )
                .alert(isPresented: $showAlert, content: {
                    getAlert(text: "This is the alert!")
            })
            }
        } // END: NAV
        // "START:" / "END:" inline comments help you locate paired container closures in large files
    }
    
    /// This is the foreground layer that holds a scrollView.
    // triple-slash comment; Option+Click on "foregroundLayer" anywhere in this file shows this description
    private var foregroundLayer: some View {
        ScrollView { // START: SCROLLV
            Text("Hello")
            ForEach(data, id: \.self) { name in
                Text(name)
                    .font(.headline)
            }
        } // END: SCROLLV
    }
    
    // MARK: FUNCTIONS
    
    /// Gets an alert with a specified title.
    ///
    /// This function creates and returns an alert immediately. The alert will have a title based on the text parameter but it will NOT have a message.
    /// ```
    /// getAlert(text: "Hi") -> Alert(title: Text("Hi"))
    /// ```
    ///
    /// - Warning: There is no additional message in this Alert.
    /// - Parameter text: This is the title for the alert.
    /// - Returns: Returns an alert with a title.
    func getAlert(text: String) -> Alert {
        return Alert(title: Text(text))
    }
}

    // MARK: PREVIEW

struct DocumentationBootcamp_Previews: PreviewProvider {
    static var previews: some View {
        DocumentationBootcamp()
    }
}

Code Walkthrough

1. // MARK: PROPERTIES — Creates a named divider in Xcode's Jump Bar. Click the file name in the breadcrumb bar at the top of the editor to see a dropdown of all MARK sections. This makes large files navigable without scrolling.

2. // MARK: - vs // MARK: — Adding a dash after MARK: adds a visual separator line in the Jump Bar dropdown. Use // MARK: - Section Name for top-level sections and // MARK: Section Name (no dash) for subsections. The code here uses no dash, but adding dashes to the major sections is a common team convention.

3. /* 1) Fix title / 2) Fix alert */ — A multi-line block comment used as a quick TODO list. Unlike task comments (// TODO: and // FIXME:), these don't appear in Xcode's Issue Navigator. Use // TODO: for issues you want Xcode to surface, and block comments for notes that should stay local.

4. // START: NAV and // END: NAV — A personal convention for marking paired container closures. In SwiftUI, deeply nested view hierarchies can have many closing braces — labeling the opening and closing of a major container helps you navigate them quickly.

5. /// This is the foreground layer that holds a scrollView. — A single-line doc comment on the computed property. Option+Click on foregroundLayer anywhere in the file shows this description in Quick Help. Even one sentence is better than nothing for non-obvious properties.

6. Full doc comment on getAlert — Demonstrates all four documentation fields: a description, a fenced code example, - Warning:, - Parameter text:, and - Returns:. This is the level of documentation appropriate for any function that is part of a shared component, a public API, or a view model method.

7. // MARK: PREVIEW — Placing the preview struct in its own MARK section makes it easy to collapse or navigate away from the preview code when working on the view logic.

Common Mistakes

Mistake: Using // instead of /// and wondering why Quick Help is empty
Only /// triple-slash comments are parsed as documentation. Double-slash // comments are invisible to Quick Help. The shortcut to generate the doc comment template for a function is Option+Command+/ with the cursor on the function signature.

Mistake: Putting // MARK: comments inside a function body
MARK comments only produce Jump Bar entries when they are at the top level of a type or file scope. A // MARK: inside a function body is just a regular comment — it won't create a navigation entry.

Mistake: Over-documenting with /// comments on every single property, including obvious ones
Documentation should reduce ambiguity, not restate code. /// The title above var title: String adds no value. Reserve /// comments for functions with non-obvious behavior, parameters with constraints, return values with specific semantics, and any function that has side effects a caller might not expect.

Key Takeaways

• Use // MARK: at file/type scope to create named Jump Bar sections — this transforms large files from walls of code into navigable, structured documents.
• Write /// doc comments for any function or property whose purpose or behavior isn't obvious from its name and type; Option+Click anywhere in Xcode renders them as formatted Quick Help.
• Use - Parameter, - Returns, and - Warning fields inside doc comments to surface preconditions and expectations directly in the IDE, reducing the need for teammates to read the implementation.

Last updated: June 27, 2026