API Documentation

This library has automatic API documentation. The documentation is generated from the source code and is located in the docs/api directory. The documentation configuration is located in the typedoc.json file.

How to write documentation

The documentation is extracted from source code comments. The comments are written in JSDoc format. Documentation can be provided for any exported or non-exported name. All interfaces should, however, be well-documented as they are the main way of interacting with the library.

A comment can look something like this:

/**
 * Adds two numbers.
 * 
 * @param lhs - The first number.
 * @param rhs - The second number.
 * @returns The sum of the two numbers.
 * 
 * @example
 * ```typescript
 * const sum = add(1, 2); // 3
 * ```
 */
export function add(lhs: number, rhs: number): number {
    return lhs + rhs;
}

All JSDoc tags begin with the @ symbol. Here the basic tags are used. For a full list of tags see the TypeDoc documentation.
Documentation wirtten in this form is both exported as a part of the API documentation and available in most IDEs. It also improves the readability of the source code and the maintainability of the library documentation, because documentation is located close to the documented code.

Doc comments on non-exported names are not exported as a part of the API documentation. They are however still available in most IDEs, so can definitely be used to improve the readability of the source code and the maintainability of the library.

How to generate documentation

The documentation is generated using the typedoc command (or npm run docs). The documentation is generated from the source code and is located in the docs/api directory. The documentation configuration is located in the typedoc.json file.

How to deploy documentation

The API documentation is automatically deployed using GitHub Actions. The documentation is deployed to Cloudflare Pages (managed by Jiří Cihelka). URL for the documentation of the main branch is https://geometryjs.jiricekcz.dev/api. URL for the documentation of other branches or specific commits is not available. It can however be generated locally using the typedoc command (or npm run docs).

The generated documentation is in HTML format and cannot be viewed perfectly using the file:// protocol. It is therefore necessary to use a local web server to view the documentation.