Comments and documentation markup in Swift - Step-by-Step Execution

Concept Flow - Comments and documentation markup

Start Code

↓

Read Line

↓

Is it a Comment?

No→Execute Code

Yes↓

Ignore or Use for Docs

↓

Next Line

↩Back to Read Line

The program reads each line, checks if it's a comment or documentation markup, then either ignores it or uses it for docs, otherwise executes the code.

Execution Sample

Swift

/// Adds two numbers
func add(a: Int, b: Int) -> Int {
    // Return sum
    return a + b
}

This Swift code shows a documentation comment for a function and a normal comment inside the function.

Execution Table

Step	Line Read	Is Comment?	Comment Type	Action	Output
1	/// Adds two numbers	Yes	Documentation	Store for docs
2	func add(a: Int, b: Int) -> Int {	No	Code	Execute function declaration
3	// Return sum	Yes	Single-line comment	Ignore during execution
4	return a + b	No	Code	Return sum of a and b
5	}	No	Code	Close function

💡 End of code reached, all comments processed or ignored, function declared.

Variable Tracker

Variable	Start	After Step 2	After Step 4	Final
Function add	undefined	Declared	Ready to call	Declared

Key Moments - 2 Insights

Why does the documentation comment start with /// instead of //?

/// marks a documentation comment that tools use to generate docs, while // is a normal comment ignored by tools. See step 1 in execution_table.

Does the single-line comment inside the function affect the program output?

No, single-line comments like // Return sum are ignored during execution, as shown in step 3.

Visual Quiz - 3 Questions

Look at the execution table, what action is taken at step 1?

A Execute the code line

B Ignore the comment completely

C Store the documentation comment for docs

D Return a value

💡 Hint

Check the 'Action' column at step 1 in the execution_table.

At which step is the function declared?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look for 'Execute function declaration' in the Action column.

If the comment on step 3 was removed, what would change in the execution?

A Nothing changes in execution

B The output would change

C The function would not work

D The documentation would be missing

💡 Hint

Step 3 comment is ignored during execution, so removing it does not affect output.

Concept Snapshot

Swift comments:
// single-line comment ignored by compiler
/// documentation comment used by tools
/* multi-line comment */ for longer notes
Comments do not affect code execution but help explain code.

Full Transcript

This example shows how Swift reads code lines and identifies comments. Documentation comments start with /// and are stored for generating docs. Single-line comments with // are ignored during execution. The function is declared normally. Comments help explain code but do not change how it runs.

Practice

1. What is the main purpose of comments in Swift code?

easy

A. To create new variables

B. To make the code run faster

C. To explain the code for better understanding

D. To store user data

Solution

1. Step 1: Understand what comments do

   Comments are notes in the code that do not affect how the program runs but help explain what the code does.

2. Step 2: Identify the purpose of comments

   Comments make the code easier to read and understand for yourself and others who read the code later.

3. Final Answer:

   To explain the code for better understanding -> Option C

4. Quick Check:

   Comments explain code [OK]

Hint: Comments explain code, not run it or store data [OK]

Common Mistakes:

• Thinking comments speed up code
• Confusing comments with variables
• Using comments to store data

2. Which of the following is the correct syntax for a single-line comment in Swift?

easy

A. # This is a comment

B. /* This is a comment */

C.

D. // This is a comment

Solution

1. Step 1: Recall Swift comment syntax

   Swift uses // for single-line comments and /* */ for multi-line comments.

2. Step 2: Match the correct syntax

   // This is a comment uses // which is the correct single-line comment syntax in Swift.

3. Final Answer:

   // This is a comment -> Option D

4. Quick Check:

   Single-line comment = // [OK]

Hint: Single-line comments start with // in Swift [OK]

Common Mistakes:

• Using /* */ for single-line comments
• Using HTML style comments
• Using # which is not a comment in Swift

3. What will the following Swift code output?

/// Adds two numbers
func add(_ a: Int, _ b: Int) -> Int {
    return a + b
}
print(add(3, 4))

medium

A. 7

B. add(3, 4)

C. /// Adds two numbers

D. Error: Unexpected documentation comment

Solution

1. Step 1: Understand documentation comments effect

   The line starting with /// is a documentation comment and does not affect the code execution.

2. Step 2: Execute the function call

   The function add returns the sum of 3 and 4, which is 7, and print outputs it.

3. Final Answer:

   7 -> Option A

4. Quick Check:

   Documentation comment ignored, output = 7 [OK]

Hint: Documentation comments don't change output, only explain [OK]

Common Mistakes:

• Thinking documentation comments print text
• Expecting error from documentation comments
• Confusing comments with code

4. Identify the error in this Swift code snippet:

/* This is a multi-line comment
func greet() {
    print("Hello")
}
// Missing closing comment delimiter

medium

A. Using // inside multi-line comment is invalid

B. Missing closing */ for multi-line comment

C. Function greet() is not declared properly

D. print statement syntax error

Solution

1. Step 1: Check multi-line comment syntax

   Multi-line comments start with /* and must end with */ to close properly.

2. Step 2: Identify missing closing delimiter

   The code has /* but no closing */, so the comment never ends, causing a syntax error.

3. Final Answer:

   Missing closing */ for multi-line comment -> Option B

4. Quick Check:

   Multi-line comment must close with */ [OK]

Hint: Multi-line comments need /* and */ to open and close [OK]

Common Mistakes:

• Ignoring missing closing comment delimiter
• Thinking // can't be inside multi-line comments
• Assuming function syntax is wrong

5. You want to document a Swift function so that Xcode shows its description and parameters clearly. Which comment style should you use?

func multiply(_ x: Int, _ y: Int) -> Int {
    return x * y
}

hard

A. /// Multiplies two numbers
/// - Parameters:
/// - x: The first number
/// - y: The second number
/// - Returns: The product of x and y

B. /* Multiplies two numbers */

C. // This function multiplies two numbers

D.

Solution

1. Step 1: Understand documentation comment usage

   Documentation comments in Swift use /// and special markup to describe functions and parameters for tools like Xcode.

2. Step 2: Identify the detailed documentation style

   /// Multiplies two numbers /// - Parameters: /// - x: The first number /// - y: The second number /// - Returns: The product of x and y uses /// with - Parameters and - Returns tags, which is the correct way to document for Xcode's quick help.

3. Final Answer:

   /// Multiplies two numbers /// - Parameters: /// - x: The first number /// - y: The second number /// - Returns: The product of x and y -> Option A

4. Quick Check:

   Use /// with parameter tags for documentation [OK]

Hint: Use /// with - Parameters and - Returns for Xcode docs [OK]

Common Mistakes:

• Using single-line or multi-line comments without markup
• Using HTML style comments
• Not including parameter descriptions