Writing Documentation

Documentation for Source bundles is generated used by Source using the typedoc tool. There are two types: HTML and JSON documentation.

By reading comments and type annotations, typedoc is able to generate both human readable documentation and documentation in the form of JSON.

By default, typedoc does type checking for the code, similar to tsc. It has been turned off as more often then not, tsc will be run before typedoc, making the type checking performed by typedoc extraneous. This does mean that if the build script is called without running tsc, there is a possibility that type errors will cause typedoc to crash.

Writing Documentation

typedoc reads both Typescript type annotations, as well as TSDOC style comments. It will build documentation for all functions and constants exported by the particular module.

Let us look at an example from the curve module.

// curve/functions.ts
/**
 * Makes a Point with given x and y coordinates.
 *
 * @param x x-coordinate of new point
 * @param y y-coordinate of new point
 * @returns with x and y as coordinates
 * @example
 * ```
 * const point = make_point(0.5, 0.5);
 * ```
 */
export function make_point(x: number, y: number): Point {
  return new Point(x, y, 0, [0, 0, 0, 1]);
}

// curve/index.ts
export { make_point } from './functions.ts';

Since the curve bundle exports the make_point function, typedoc will generate documentation for it.

HTML Documentation

The human readable documentation resides in the build/documentation folder. You can view its output here. This is what the output for make_point looks like:

JSON Documentation

To provide the frontend with documentation that can be directly displayed to the user, each module has its own json file in the jsons folder containing the formatted descriptions of exported variables. Using the example code above, here is what the JSON documentation looks like for the actual curve bundle:

{
  "b_of": "<div><h4>b_of(pt: Point) → {number}</h4><div class=\"description\"><p>Retrieves the blue component of a given Point.</p></div></div>",
  "make_point": "<div><h4>make_point(x: number, y: number) → {Point}</h4><div class=\"description\"><p>Makes a Point with given x and y coordinates.</p></div></div>",
  // ... and other functions and constants
}

This is then displayed by the frontend:

When building the json documentation for a bundle, the following steps are taken:

1. From typedoc's output, extract the project corresponding to the bundle.
2. For each exported variable, run it through a converter to convert the typedoc project into a single string:
   • For constants, their names and types are extracted
   • For functions, their name, the names and types of each parameter, and return types are extracted.
     The descriptions of both functions are constants are also included, but first they are passed through a Markdown to HTML converter called drawdown, included in this project as drawdown.ts
3. The code then converts it to the HTML format expected by the frontend
4. All the processed strings then get written to a json file in the jsons folder.

If no documentation could be found, or there was an error parsing the documented code, the system will still output jsons, just with warnings.