Skip to main content
On this page

deno doc, documentation generator

Command-line Usage

deno doc [OPTIONS] [source_file]...

Show documentation for a module.

Output documentation to standard output:

deno doc ./path/to/module.ts

Output documentation in HTML format:

deno doc --html --name="My library" ./path/to/module.ts

Lint a module for documentation diagnostics:

deno doc --lint ./path/to/module.ts

Target a specific symbol:

deno doc ./path/to/module.ts MyClass.someField

Show documentation for runtime built-ins:

deno doc
deno doc --filter Deno.Listener

Dependency management options Jump to heading

--import-map Jump to heading

Load import map file from local file or remote URL.

--lock Jump to heading

Check the specified lock file. (If value is not provided, defaults to "./deno.lock").

--no-lock Jump to heading

Disable auto discovery of the lock file.

--no-npm Jump to heading

Do not resolve npm modules.

--no-remote Jump to heading

Do not resolve remote modules.

--reload Jump to heading

Short flag: -r

Reload source code cache (recompile TypeScript) no value Reload everything jsr:@std/http/file-server,jsr:@std/assert/assert-equals Reloads specific modules npm: Reload all npm modules npm:chalk Reload specific npm module.

Options Jump to heading

--allow-import Jump to heading

Short flag: -I

Allow importing from remote hosts. Optionally specify allowed IP addresses and host names, with ports as necessary. Default value: deno.land:443,jsr.io:443,esm.sh:443,raw.githubusercontent.com:443,user.githubusercontent.com:443.

Documentation options Jump to heading

--category-docs Jump to heading

Path to a JSON file keyed by category and an optional value of a markdown doc.

--default-symbol-map Jump to heading

Uses the provided mapping of default name to wanted name for usage blocks.

--filter Jump to heading

Dot separated path to symbol.

--html Jump to heading

Output documentation in HTML format.

--json Jump to heading

Output documentation in JSON format.

--lint Jump to heading

Output documentation diagnostics.

--name Jump to heading

The name that will be used in the docs (ie for breadcrumbs).

--output Jump to heading

Directory for HTML documentation output.

--private Jump to heading

Output private documentation.

--strip-trailing-html Jump to heading

Remove trailing .html from various links. Will still generate files with a .html extension.

--symbol-redirect-map Jump to heading

Path to a JSON file keyed by file, with an inner map of symbol to an external link.

Examples Jump to heading

deno doc followed by a list of one or more source files will print the JSDoc documentation for each of the module's exported members.

For example, given a file add.ts with the contents:

/**
 * Adds x and y.
 * @param {number} x
 * @param {number} y
 * @returns {number} Sum of x and y
 */
export function add(x: number, y: number): number {
  return x + y;
}

Running the Deno doc command, prints the function's JSDoc comment to stdout:

deno doc add.ts
function add(x: number, y: number): number
  Adds x and y. @param {number} x @param {number} y @returns {number} Sum of x and y

Linting Jump to heading

You can use --lint flag to check for problems in your documentation while it's being generated. deno doc will point out three kinds of problems:

  1. Error for an exported type from the root module referencing a non-exported type.
    • Ensures API consumers have access to all the types the API uses. This can be suppressed by exporting the type from a root module (one of the files specified to deno doc on the command line) or by marking the type with an @internal jsdoc tag.
  2. Error for missing return type or property type on a public type.
    • Ensures deno doc displays the return/property type and helps improve type checking performance.
  3. Error for missing JS doc comment on a public type.
    • Ensures the code is documented. Can be suppressed by adding a jsdoc comment, or via an @ignore jsdoc tag to exclude it from the documentation. Alternatively, add an @internal tag to keep it in the docs, but signify it's internal.

For example:

/mod.ts
interface Person {
  name: string;
  // ...
}

export function getName(person: Person) {
  return person.name;
}
$ deno doc --lint mod.ts
Type 'getName' references type 'Person' which is not exported from a root module.
Missing JS documentation comment.
Missing return type.
    at file:///mod.ts:6:1

These lints are meant to help you write better documentation and speed up type-checking in your projects. If any problems are found, the program exits with non-zero exit code and the output is reported to standard error.

Supported JSDoc tags Jump to heading

Deno implements a large set of JSDoc tags, but also additional tags that are not specified in the JSDoc specification. The following tags are supported:

  • constructor/class: mark a function to be a constructor.
  • ignore: ignore a symbol to be included in the output.
  • internal: mark a symbol to be used only for internal. In the HTML generator, the symbol will not get a listed entry, however it will still be generated and can be reached if a non-internal symbol links to it.
  • public: treat a symbol as public API. Equivalent of TypeScript public keyword.
  • private: treat a symbol as private API. Equivalent of TypeScript private keyword.
  • protected: treat a property or method as protected API. Equivalent of TypeScript protected keyword.
  • readonly: mark a symbol to be readonly, meaning that it cannot be overwritten.
  • experimental: mark a symbol as experimental, meaning that the API might change or be removed, or behaviour is not well-defined.
  • deprecated: mark a symbol as deprecated, meaning that it is not supported anymore and might be removed in a future version.
  • module: this tag can be defined on a top-level JSDoc comment, which will treat that comment to be for the file instead of the subsequent symbol.
  • category/group: mark a symbol to be of a specific category/group. This is useful for grouping together various symbols together.
  • see: define an external reference related to the symbol.
  • example: define an example for the symbol.
  • tags: define additional custom labels for a symbol, via a comma separated list.
  • since: define since when the symbol has been available.
  • callback: define a callback.
  • template/typeparam/typeParam: define a callback.
  • prop/property: define a property on a symbol.
  • typedef: define a type.
  • param/arg/argument: define a parameter on a function.
  • return/returns: define the return type and/or comment of a function.
  • throws/exception: define what a function throws when called.
  • enum: define an object to be an enum.
  • extends/augments: define a type that a function extends on.
  • this: define what the this keyword refers to in a function.
  • type: define the type of a symbol.
  • default: define the default value for a variable, property or field.

HTML output Jump to heading

Use the --html flag to generate a static site with documentation.

$ deno doc --html --name="My library" ./mod.ts

$ deno doc --html --name="My library" --output=./documentation/ ./mod.ts

$ deno doc --html --name="My library" ./sub1/mod.ts ./sub2/mod.ts

The generated documentation is a static site with multiple pages that can be deployed to any static site hosting service.

A client-side search is included in the generated site, but is not available if user's browser has JavaScript disabled.

JSON output Jump to heading

Use the --json flag to output the documentation in JSON format. This JSON format is consumed by the deno doc website and is used to generate module documentation.