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:
- 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.
- 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
- 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.
- Ensures
- 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.
- Ensures the code is documented. Can be suppressed by adding a jsdoc
comment, or via an
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 TypeScriptpublic
keyword.private
: treat a symbol as private API. Equivalent of TypeScriptprivate
keyword.protected
: treat a property or method as protected API. Equivalent of TypeScriptprotected
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 thethis
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.