Why deno doc for documentation? - Purpose & Use Cases

The Big Idea

Discover how to never worry about outdated docs again with a simple Deno command!

The Scenario

Imagine writing a large Deno project and trying to keep track of all your functions, classes, and types by hand in a separate document.

Every time you change your code, you must update the docs manually.

The Problem

Manually updating documentation is slow and easy to forget.

It leads to outdated or incorrect docs that confuse users and developers.

It's hard to keep docs in sync with code changes.

The Solution

deno doc automatically generates up-to-date documentation directly from your source code comments and types.

This keeps docs accurate and saves you time.

Before vs After

✗ Before

/*
 * Adds two numbers
 */
function add(a, b) {
  return a + b;
}
// Update docs manually when code changes

✓ After

/// Adds two numbers
function add(a: number, b: number): number {
  return a + b;
}
// Run 'deno doc' to generate docs automatically

What It Enables

It enables effortless, always-accurate documentation that grows with your code.

Real Life Example

A team working on a Deno API can generate clear docs instantly after every update, so everyone understands how to use the API without confusion.

Key Takeaways

Manual docs are slow and error-prone.

deno doc automates documentation from code comments and types.

This keeps docs accurate and saves time.

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