ende doc

Examples

ende 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 Ende doc command prints the function's JSDoc comment to stdout:

ende 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

Documenting a JSR package

ende doc accepts jsr: specifiers and will fetch the package's published types before generating documentation. This is useful for exploring a third-party API from the terminal without cloning the repository:

ende doc jsr:@ende/path

You can pin to a specific version like any other Ende specifier (jsr:@ende/[email protected]), and combine the specifier with --html or --json to render the same output formats as for local files.

Linting

You can use --lint flag to check for problems in your documentation while it's being generated. ende 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 ende 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 ende 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;
}

ende 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 features and tags

Ende 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.

Supported Tags

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.
• 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. 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 Linking

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.ende.sh}, which will be rendered as the following 'https://docs.ende.sh'. {@linkcode https://docs.ende.sh} can also be used, to make it in a monospace font, and will be rendered roughly like this: 'https://docs.ende.sh'.

You can also specify a replacement label, via {@link https://docs.ende.sh | Ende Docs}, which will use the text after | as the text to display instead of the link. The previous example would render as 'Ende 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}.

HTML output

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

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

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

ende 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

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

doc