Package Documentation Guide

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

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:

// someFile.ts

const foo = 42;

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:

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

import { sum } from 'foo';

// Output: `5`
console.log(sum(2, 3));

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