runtime/reference/cli/doc.md
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
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:
deno doc on the command line) or by marking the type with an
@internal jsdoc tag.deno doc displays the return/property type and helps improve type
checking performance.@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.
Deno implements a large set of JSDoc tags, but does not strictly adhere to the JSDoc standard, but rather align with sensible standards and features provided by widely used tools and ecosystems in the same feature-space, like TSDoc and TypeDoc.
For any free-form text places, ie the main description of a JSDoc comment, the description of a parameter, etc. accept markdown.
The following tags are supported, being a selection of tags used and specified by JSDoc, TSDoc and TypeDoc:
constructor/class: mark a function to be a
constructor.ignore: ignore a symbol to be included in
the output.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. A value can be specified, which will use the
value as an identifier for the module (ie for default exports).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.
Unlike JSDoc, code examples need to be wrapped in triple backtick
(markdown-style codeblocks), which aligns more with TSDoc than JSDoc.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 generic parameter.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.Inline links let you specify links to other parts of the page, other symbols, or modules. Besides just supporting markdown-style links, JSDoc style inline-links are also supported.
For example, you can do{@link https://docs.deno.com}, which will be rendered
as the following 'https://docs.deno.com'. {@linkcode https://docs.deno.com}
can also be used, to make it in a monospace font, and will be rendered roughly
like this: 'https://docs.deno.com'.
You can also specify a replacement label, via
{@link https://docs.deno.com | Deno Docs}, which will use the text after |
as the text to display instead of the link. The previous example would render as
'Deno Docs'.
You can add inline links in your descriptions to other symbols via
{@link MySymbol}.
For module linking, the same applies, but you use the {@link [myModule]}
syntax. You can also link to symbols in a different module via
{@link [myModule].mysymbol}.
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.
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.