deno doc for documentation - Step-by-Step Execution

Concept Flow - deno doc for documentation

Write Deno code with comments

↓

Run 'deno doc' command

↓

Deno parses code and comments

↓

Generate structured documentation output

↓

View docs in terminal or browser

This flow shows how Deno reads your code and comments, then creates documentation you can read.

Execution Sample

Deno

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

console.log(add(2, 3));

This code defines a function with a comment, then logs the result of calling it.

Execution Table

Step	Action	Input	Output/Result
1	Read source file	Code with /// comment	Code and comment loaded
2	Parse comments	/// Adds two numbers	Extract function description
3	Parse function signature	function add(a: number, b: number): number	Identify function name and parameters
4	Generate documentation	Parsed info	Create structured doc for 'add'
5	Display documentation	Doc data	Show function name, params, and comment
6	Exit	No more code	Documentation complete

💡 All code parsed and documentation generated

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
sourceCode	empty	loaded with code and comments	same	same	same
comments	none	extracted 'Adds two numbers'	same	same	same
functions	none	none	identified 'add' with params	same	same
documentation	none	none	none	created doc for 'add'	final doc ready

Key Moments - 2 Insights

Why does 'deno doc' only show comments starting with ///?

Because 'deno doc' looks for triple-slash comments (///) as documentation comments, as shown in step 2 of the execution_table where it extracts those comments.

What happens if a function has no comment above it?

In step 2 and 4, no comment is extracted or added to the documentation, so the function appears without description in the output.

Visual Quiz - 3 Questions

Look at the execution_table, what is extracted at step 2?

A Function signature

B Console output

C Triple-slash comments

D Variable values

💡 Hint

Check the 'Action' and 'Output/Result' columns at step 2 in the execution_table

At which step does 'deno doc' identify function parameters?

A Step 1

B Step 3

C Step 2

D Step 5

💡 Hint

Look for 'Parse function signature' in the execution_table

If you remove the /// comment, what changes in the documentation?

A No description shown

B Parameters disappear

C Function name disappears

D Documentation generation fails

💡 Hint

Refer to key_moments about missing comments and their effect on documentation

Concept Snapshot

deno doc generates docs from /// comments
Run: deno doc <file.ts>
Parses code and comments
Outputs structured docs
Shows function names, params, descriptions
No comment means no description

Full Transcript

Deno doc reads your TypeScript or JavaScript code and looks for triple-slash comments (///) above functions or variables. It parses these comments as documentation. Then it reads the function signatures to get names and parameters. Finally, it creates a structured documentation output you can view in the terminal or browser. If a function lacks a /// comment, it appears without description. This process helps you keep your code documented clearly and automatically.

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