deno doc for documentation - Mini Project: Build & Apply

Using deno doc for Documentation

📖 Scenario: You are building a small Deno module that exports some functions. You want to create clear documentation for your code so others can understand how to use it.

🎯 Goal: Create a Deno module with functions and use deno doc to generate documentation from your code comments.

📋 What You'll Learn

Create a Deno module file named math_utils.ts with two exported functions.

Add JSDoc comments to each function explaining what it does.

Use deno doc command to generate documentation for the module.

Include a configuration variable to control documentation output format.

💡 Why This Matters

🌍 Real World

Writing clear documentation helps other developers understand and use your code easily. Tools like deno doc automate this process by extracting comments.

💼 Career

Documentation skills are essential for software developers to maintain code quality and support teamwork. Knowing how to use documentation tools like deno doc is valuable in professional Deno projects.

1

Create the Deno module with exported functions

Create a file named math_utils.ts and write two exported functions: add that takes two numbers and returns their sum, and multiply that takes two numbers and returns their product.

Deno

// Your code here

Hint

Use export function syntax to make functions available outside the module.

2

Add JSDoc comments to the functions

Add JSDoc comments above each function in math_utils.ts. For add, write: "Adds two numbers and returns the sum." For multiply, write: "Multiplies two numbers and returns the product."

Deno

export function add(a: number, b: number): number {
  return a + b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}

// Add JSDoc comments above each function

Hint

Use /** ... */ syntax to write JSDoc comments.

3

Create a config variable for documentation format

In math_utils.ts, add a constant variable named docFormat and set it to the string "json" to specify the documentation output format.

Deno

/**
 * Adds two numbers and returns the sum.
 */
export function add(a: number, b: number): number {
  return a + b;
}

/**
 * Multiplies two numbers and returns the product.
 */
export function multiply(a: number, b: number): number {
  return a * b;
}

// Add a constant named docFormat with value "json"

Hint

Use const docFormat = "json"; to create the variable.

4

Use deno doc command to generate documentation

Run the command deno doc math_utils.ts --json in your terminal to generate JSON formatted documentation for the math_utils.ts module.

Deno

const docFormat = "json";

/**
 * Adds two numbers and returns the sum.
 */
export function add(a: number, b: number): number {
  return a + b;
}

/**
 * Multiplies two numbers and returns the product.
 */
export function multiply(a: number, b: number): number {
  return a * b;
}

// Run `deno doc math_utils.ts --json` in terminal

Hint

Use the terminal to run deno doc math_utils.ts --json to see the documentation output.

Practice

1. What is the main purpose of the deno doc command?

easy

A. To run Deno scripts with debugging enabled

B. To install third-party Deno modules

C. To display easy-to-read documentation for your Deno code

D. To format Deno code automatically

Solution

1. Step 1: Understand the role of deno doc

   deno doc is designed to show documentation for Deno code in a clear and readable way.

2. Step 2: Compare with other options

   Running scripts, installing modules, or formatting code are done by other commands, not deno doc.

3. Final Answer:

   To display easy-to-read documentation for your Deno code -> Option C

4. Quick Check:

   Documentation = Display code info [OK]

Hint: Remember: doc means documentation, not running code [OK]

Common Mistakes:

• Confusing deno doc with running scripts
• Thinking it installs modules
• Assuming it formats code automatically

2. Which of the following is the correct way to write a comment that deno doc will use for documentation?

easy

A. # This is a hash comment

B. /* This is a block comment */

C. // This is a normal comment

D. /// This is a documentation comment

Solution

1. Step 1: Identify comment style for deno doc

   deno doc uses triple slash /// comments to generate documentation.

2. Step 2: Check other comment types

   Single slashes and block comments are normal comments, hash comments are not valid in Deno.

3. Final Answer:

   /// This is a documentation comment -> Option D

4. Quick Check:

   Triple slash = doc comment [OK]

Hint: Use triple slashes for doc comments with deno doc [OK]

Common Mistakes:

• Using single or block comments for documentation
• Using hash (#) comments from other languages
• Not using any comment before functions or variables

3. Given this code snippet, what will deno doc example.ts show for the function add?

/// Adds two numbers
function add(a: number, b: number): number {
  return a + b;
}

medium

A. Function add(a: number, b: number): number - Adds two numbers

B. No output because comments are ignored

C. Syntax error due to missing export

D. Only the function signature without comments

Solution

1. Step 1: Check comment usage

   The triple slash comment above the function is used by deno doc to show description.

2. Step 2: Understand output format

   deno doc shows the function signature plus the comment as description.

3. Final Answer:

   Function add(a: number, b: number): number - Adds two numbers -> Option A

4. Quick Check:

   Doc comment + signature = detailed output [OK]

Hint: Doc comments appear with function signatures in output [OK]

Common Mistakes:

• Thinking comments are ignored
• Assuming export is required for doc
• Expecting only signature without comments

4. You run deno doc myfile.ts but get no documentation output. What is the most likely cause?

medium

A. You forgot to install Deno

B. The file has no triple slash /// comments

C. The file is missing a main function

D. The file uses single-line comments only

Solution

1. Step 1: Check comment style in the file

   deno doc requires triple slash /// comments to generate documentation.

2. Step 2: Understand other options

   Missing main function or single-line comments do not affect deno doc output; Deno must be installed to run the command.

3. Final Answer:

   The file has no triple slash /// comments -> Option B

4. Quick Check:

   No triple slash comments = no doc output [OK]

Hint: Check for triple slash comments if doc output is empty [OK]

Common Mistakes:

• Assuming main function is needed for documentation
• Confusing single-line comments with doc comments
• Not verifying Deno installation before running command

5. You want to generate JSON documentation for a remote Deno module at https://deno.land/std@0.200.0/fs/mod.ts. Which command will correctly produce JSON output?

hard

A. deno doc --json https://deno.land/std@0.200.0/fs/mod.ts

B. deno doc https://deno.land/std@0.200.0/fs/mod.ts --json

C. deno doc --json -r https://deno.land/std@0.200.0/fs/mod.ts

D. deno doc -j https://deno.land/std@0.200.0/fs/mod.ts

Solution

1. Step 1: Identify correct flag usage for JSON output

   The --json flag must come before the file or URL argument in deno doc.

2. Step 2: Check command syntax

   deno doc --json https://deno.land/std@0.200.0/fs/mod.ts places --json before the URL, which is correct. Other options either place flags incorrectly or use invalid flags.

3. Final Answer:

   deno doc --json https://deno.land/std@0.200.0/fs/mod.ts -> Option A

4. Quick Check:

   --json before URL = correct syntax [OK]

Hint: Put --json before file or URL for JSON output [OK]

Common Mistakes:

• Placing --json after the URL
• Using shorthand -j which is invalid
• Adding extra flags like -r that don't exist