Documenting a function with a comment
Name:
Date:
Class:
A
Quick Questions
Shade in the A or B circle for each question.
1. Which comment style is used to document a function above its declaration?
2. Which tag describes an input a function receives?
3. Which tag describes the value a function gives back?
4. Which comment explains the purpose of the code better?
5. Which doc comment line correctly documents a parameter called name that is a string?
B
Match the Pairs
Draw a line connecting each item on the left to its match on the right.
| Left column | Right column | |
|---|---|---|
| 1/** Adds two numbers together. */ | AA doc comment placed above a function that states what the function does | |
| 2@param {number} price - Cost of one item | B/** @returns {number} The total cost */ | |
| 3A doc comment states what the function returns using the @returns tag | CA tag that names an input to the function, gives its type and says what it is | |
| 4A good comment explains the purpose of the function, not just a repeat of the code | DThe comment just repeats the code in words and does not explain the purpose | |
| 5/* Adds two numbers */ function add(a, b) { return a + b; } | EThe comment starts with /* instead of /**, so it is a normal block comment and not a doc comment | |
| 6// Sets x to x + 1 let x = x + 1; | F// Checks if a student passed (mark 50 or more) |
C
Definitions
/** ... */
D
Fill in the Blanks
Complete each line of code by filling in the missing parts.
1.
___ Adds two numbers together. */
function add(a, b) { return a + b; }
2.
/**
* @_____ {number} a - the first number
*/
3.
/**
* @_______ {number} The total of a and b
*/
4.
__ Checks if a number is even
function isEven(n) { return n % 2 === 0; }
5.
/** @param {number} _ - number to check */
function isEven(n) { return n % 2 === 0; }
E
Spot the Error
Shade in the letter of the line that contains an error.
Question 1
A
/* Adds two numbers. */
B
function add(a, b) {
C
return a + b;
D
}
Question 2
A
/**
B
* @param {number} n - The input.
C
* @retuns {number} n doubled.
D
*/
E
const twice = n => n * 2;
Question 3
A
/** Area of a circle.
B
function area(r) {
C
return Math.PI * r * r;
D
}
Question 4
A
// Larger of two numbers
B
function max2(a, b) {
C
return a > b ? b : a;
D
}
Question 5
A
/**
B
* Greets a player by name.
C
* param {string} n - The name.
D
*/
E
const hi = n => 'Hi ' + n;
Answer Key
Documenting a function with a comment
Section A: Quick Questions
Q1
B — /** What the function does */
Q2
A — @param
Q3
B — @returns
Q4
A — // Works out the total cost including GST
Q5
A — @param {string} name - The player's name
Section B: Match the Pairs
Q1
/** Adds two numbers together. */ → A doc comment placed above a function that states what the function does
Q2
@param {number} price - Cost of one item → A tag that names an input to the function, gives its type and says what it is
Q3
A doc comment states what the function returns using the @returns tag → /** @returns {number} The total cost */
Q4
A good comment explains the purpose of the function, not just a repeat of the code → // Checks if a student passed (mark 50 or more)
Q5
/* Adds two numbers */
function add(a, b) { return a + b; } → The comment starts with /* instead of /**, so it is a normal block comment and not a doc comment
Q6
// Sets x to x + 1
let x = x + 1; → The comment just repeats the code in words and does not explain the purpose
Section C: Definitions
Q1
/** ... */ — A doc comment placed above a function. It says what the function does, lists its inputs with @param and its output with @returns, so others can use it without reading the code.Section D: Fill in the Blanks
Q1
/** Adds two numbers together. */
function add(a, b) { return a + b; }Q2
/**
* @param {number} a - the first number
*/Q3
/**
* @returns {number} The total of a and b
*/Q4
// Checks if a number is even
function isEven(n) { return n % 2 === 0; }Q5
/** @param {number} n - number to check */
function isEven(n) { return n % 2 === 0; }Section E: Spot the Error
Q1
A — A doc comment must start with /** (two stars). A single star makes an ordinary comment that documentation tools ignore. It should be /** Adds two numbers. */
Q2
C — The tag is misspelled. The tag that describes the output is @returns, so the line should be ' * @returns {number} n doubled.'
Q3
A — The doc comment is never closed. It needs */ at the end, otherwise the code below becomes part of the comment. It should be /** Area of a circle. */
Q4
C — The comment says the function gives the larger number, but this line returns the smaller one when a > b. It should be return a > b ? a : b;
Q5
C — The @ is missing, so 'param' is just plain text and not a tag. It should be ' * @param {string} n - The name.'