Package Documentation Guide

This guide explains how you can improve the documentation of your packages as displayed on jsDocs.io.

Package Analysis Process

Visiting the documentation page for a package (for example, jsdocs.io/package/foo) starts the following analysis process:

  1. Query the npm registry for the manifest describing package foo at its latest version (for example, 1.0.0)
  2. Download the tarball containing package foo@1.0.0 from the npm registry
  3. Extract the package's public API from the downloaded files:
    1. Find the package's index file (for example, index.ts or index.d.ts)
    2. Extract the package's overview from the index file
    3. Find all the declarations exported from the index file
  4. Render the documentation page

In the following sections, you will learn how to optimize the metadata extracted from your package through this process.

Supported Packages

Due to the diversity of the Javascript ecosystem and current technical limitations, the public API can only be extracted from packages that:

  • Provide exports through a single entry point file (for example, index.ts) using module export forms;
    in other words, a user would import functionalities from the package as import ... from 'foo'
  • Include Typescript definition files (.d.ts) and/or Typescript source files (.ts);
    untyped (Javascript-only) packages are not currently supported
  • Specify a license property inside package.json that:
    • Is not empty
    • Is not UNLICENSED
    • Does not start with SEE (for example, SEE LICENSE IN ...)

In practice, most open source Typescript and Javascript packages that provide their own type definitions should be well supported.

If a package does not include type definitions (for example, a Javascript-only package) but some are available thanks to the Definitely Typed project, that package's documentation page will contain a link to the corresponding @types package.

Including Type Definition Files

To include Typescript definition files (.d.ts) and, optionally, Typescript source files (.ts) when publishing your package to npm, you need to set the files property inside package.json with the desired file patterns.

You also need to set the types property and, optionally, the source property inside package.json to point to the main type definition file and source file respectively.

For example, consider the following project structure where src contains the source file named index.ts and dist contains the type definition file named index.d.ts:

.
├── src
│   └── index.ts
├── dist
│   ├── index.js
│   └── index.d.ts
└── package.json

To include both the src and dist directories in your published npm package and to set index.d.ts as the main type definition file and index.ts as the main source file, your package's package.json file should look like this:

// package.json
{
"name": "your-package-name",
"version": "1.0.0",
"source": "./src/index.ts",
"types": "./dist/index.d.ts",
"files": [
"src",
"dist"
],
...
}

Index File

The index file is the single entry point to your package from which you should export all the public declarations using module export forms.

The following example shows a simple index file with one direct export and a module re-export:

// index.ts
// Re-export all the declarations from another module
export * from './other-module';
// Direct export
export const name = 'foo';

The name of your package's index file must match one of the following filenames, listed in order of preference:

  1. The name of the Typescript source file (.ts) present in the source property inside package.json
  2. The name of the Typescript type definition file (.d.ts) present in the types (or typings) property inside package.json
  3. The fixed name public-package-api.ts
  4. The name of your package followed by the .ts extension (for example, foo.ts if your package is named foo)
  5. The fixed name index.ts
  6. The fixed name main.ts
  7. The fixed name public-package-api.d.ts
  8. The name of your package followed by the .d.ts extension (for example, foo.d.ts if your package is named foo)
  9. The fixed name index.d.ts
  10. The fixed name main.d.ts

In case of conflicts (for example, two or more files named index.ts), the file with the shortest path and that comes first in alphabetical order is selected.

Package Overview

The overview is the first documentation section displayed in your package's documentation page. You can use it to introduce your package, describe its functionalities, show examples and provide any other relevant information.

To write your package's overview, add a documentation comment containing the @packageDocumentation tag to your package's index file like in the following example:

// index.ts
/**
* This is the package overview, denoted by the `@packageDocumentation` tag at the end.
*
* In this first section, you can provide a quick summary of your package.
*
* @remarks
* In the remarks section, you can expand on important concepts.
*
* Inside documentation comments, you can use all the features supported by the
* {@link https://github.com/microsoft/tsdoc | TSDoc standard} such as:
*
* @example
* Links:
* {@link https://www.example.com}
*
* Links with custom text:
* {@link https://www.example.com | Example.com}
*
* Links to declarations in your own package:
* {@link someFunction},
* {@link SomeClass.someMethod | someMethod from SomeClass}
*
* Links to declarations in other packages:
* {@link short-time-ago#timeAgo | timeAgo function from package `short-time-ago`}
*
* @example
* Inline code:
* `ENV_VAR='true'`
*
* @example
* Code blocks:
* ```typescript
* // someFile.ts
*
* const foo = 42;
* ```
*
* @see {@link https://github.com/microsoft/tsdoc | TSDoc repository} for the standard
* @see {@link https://microsoft.github.io/tsdoc | TSDoc playground} for more examples
*
* @packageDocumentation
*/

The documentation comment above is rendered according to the TSDoc standard as follows:

This is the package overview, denoted by the @packageDocumentation tag at the end.

In this first section, you can provide a quick summary of your package.

Remarks

In the remarks section, you can expand on important concepts.

Inside documentation comments, you can use all the features supported by the TSDoc standard such as:

Example 1

Links: https://www.example.com

Links with custom text: Example.com

Links to declarations in your own package: someFunction, someMethod from SomeClass

Links to declarations in other packages: timeAgo function from package `short-time-ago`

Example 2

Inline code: ENV_VAR='true'

Example 3

Code blocks:

// someFile.ts
const foo = 42;

See Also

For more information and examples about TSDoc, see the TSDoc repository and the TSDoc playground.

Package Declarations

Your package can export, using module export forms, any of the following kinds of declarations:

  • Variables
  • Functions
  • Classes
  • Interfaces
  • Enums
  • Type aliases
  • Namespaces

Exported declarations should be documented using TSDoc documentation comments like in the following example:

// index.ts
/**
* `sum` returns the sum of two numbers.
*
* @param a - the first number
* @param b - the second number
* @returns the sum of a and b
*
* @example
* Usage:
* ```typescript
* import { sum } from 'foo';
*
* // Output: `5`
* console.log(sum(2, 3));
* ```
*
* @see {@link https://en.wikipedia.org/wiki/Addition | Addition on Wikipedia}
*/
export function sum(a: number, b: number): number {
return a + b;
}

The documentation for the sum function defined above is rendered as follows:

function sum

sum: (a: number, b: number) => number;

sum returns the sum of two numbers.

Parameter a

the first number

Parameter b

the second number

Returns

the sum of a and b

Example 1

Usage:

import { sum } from 'foo';
// Output: `5`
console.log(sum(2, 3));

See Also

To prevent an exported declaration from being documented, use the @internal tag in its documentation comment. Note that private declarations (for example, the private fields or methods of a class) and declarations with names starting with an underscore (for example, _foo) are never documented.

For more information about tags, see TsDoc standard tags.

Example Packages

You can use the following packages as a reference when documenting your package:

  • short-time-ago (docs, source)
    A simple package consisting of one source file exporting a single function
  • query-registry (docs, source)
    A more complex package with multiple exported declarations of different kinds
  • faastjs (docs, source)
    A third-party package that shows what is possible to achieve with a rich documentation