deno doc, documentation generator

deno doc [OPTIONS] [source_file]...

deno doc ./path/to/module.ts

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

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

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

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:

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.