← ACARA Digital Technologies Years 9–10

Documenting a function with a comment

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.

Part of: ACARA Digital Technologies Years 9–10 — Modular and Object-Oriented Programming (JavaScript) — Module 19

Understanding Documenting a function with a comment in ACARA Digital Technologies Years 9–10

What it does: @returns tells the reader what kind of value comes back from the function and what it means. This comment says why the code exists and what it is for. A comment like '// mark >= 50' would only repeat the code. A /** ... */ doc comment sits above a function and describes it.  is an HTML comment and does not work in JavaScript. Use @param followed by the type, the parameter name and a short description. @returns is only for the output. // comments out one line. /** starts a multi-line doc comment that must end with */.

Common mistakes: 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. */. The tag is misspelled. The tag that describes the output is @returns, so the line should be ' * @returns {number} n doubled.'.

Class: _____________________ · Name: _____________________ · Date: _________

Free printable worksheet with full answer key — or add this module to a class and your students practise it interactively.

🖨 Print worksheet + answer key Add Documenting a function with a comment to a class →

This module's key terms are also in a printable crossword (Modules 681–707) and word search (Modules 629–707).

Take this worksheet further — free with Cloodit

Each concept is reinforced from every angle — learned, then applied, then tested.

Learning

Duo

Which comment style is used to document a function above its declaration?

/** What the function does */

Matches

/* 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

Applying

Meanings

Term

/** ... */

Meaning

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.

Practice

/**

Testing

Gaps

Adds two numbers together. */

Check Answer

Spots

1/* Adds two numbers. */

2function add(a, b) {

Cloodit turns curriculum-aligned coding content into journeys students work through one biome at a time.

Students earn collectable badges

Over 100 of them, across seven natural biomes.

Study Buddy

Students build a real study resource

Turns their work into revision material ready for Flash Cards and Exam study.

Diamond Dash — one of Cloodit's live, competitive Sprint games

Students lock in with Sprints

Live, competitive practice for the start of the lesson or a teacher-led lesson finisher.

A Cloodit certificate of achievement, ready to personalise and print

Custom printable certificates

Honour your top performers, or encourage a student who's trying hard — ready to print in seconds.

Add to class →

Quick Questions

1. Which comment style is used to document a function above its declaration?

A.

B. /** What the function does */ ✓

A /** ... */ doc comment sits above a function and describes it.  is an HTML comment and does not work in JavaScript.

2. Which tag describes an input a function receives?

A. @param ✓

B. @returns

@param describes each parameter (input). @returns describes the value the function gives back.

3. Which tag describes the value a function gives back?

A. @param

B. @returns ✓

@returns states what comes out of the function. @param is for the inputs.

4. Which comment explains the purpose of the code better?

A. // Works out the total cost including GST ✓

B. // Multiplies price by 1.1

Good comments explain why the code exists (its purpose), not just repeat what the code does line by line.

5. Which doc comment line correctly documents a parameter called name that is a string?

A. @param {string} name - The player's name ✓

B. @returns {string} name - The player's name

Use @param followed by the type, the parameter name and a short description. @returns is only for the output.

Match the Pairs

/** Adds two numbers together. */ → A doc comment placed above a function that states what the function does

@param {number} price - Cost of one item → A tag that names an input to the function, gives its type and says what it is

A doc comment states what the function returns using the @returns tag → /** @returns {number} The total cost */

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)

/* 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

// Sets x to x + 1 let x = x + 1; → The comment just repeats the code in words and does not explain the purpose

Key Term

/** ... */

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.

Fill in the Blanks

1. /** Adds two numbers together. */ function add(a, b) { return a + b; }

Hint: Type the symbol that opens a doc comment above a function.

2. /** * @param {number} a - the first number */

Hint: Type the tag name that describes one input to the function.

3. /** * @returns {number} The total of a and b */

Hint: Type the tag name that describes the value the function gives back.

4. // Checks if a number is even function isEven(n) { return n % 2 === 0; }

Hint: Type the symbol that starts a single-line comment.

5. /** @param {number} n - number to check */ function isEven(n) { return n % 2 === 0; }

Hint: Type the parameter name that matches the one in the function below.

Spot the Error

Question 1

A /* Adds two numbers. */

B function add(a, b) {

C return a + b;

D }

Line 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. */

Question 2

A /**

B * @param {number} n - The input.

C * @retuns {number} n doubled.

D */

E const twice = n => n * 2;

Line C — The tag is misspelled. The tag that describes the output is @returns, so the line should be ' * @returns {number} n doubled.'

Question 3

A /** Area of a circle.

B function area(r) {

C return Math.PI * r * r;

D }

Line 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. */

Question 4

A // Larger of two numbers

B function max2(a, b) {

C return a > b ? b : a;

D }

Line 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;

Question 5

A /**

B * Greets a player by name.

C * param {string} n - The name.

D */

E const hi = n => 'Hi ' + n;

Line C — The @ is missing, so 'param' is just plain text and not a tag. It should be ' * @param {string} n - The name.'

Student with a class code? Join your class →