What’s Up, (Type) Doc?

David McIntosh

Mar 3, 2019·3 min read

In Software Development, there’s no substitute for good documentation. Regardless of how well-written your code may be, there will always be questions, and those questions can often be easily answered by documentation. The problem with developers, especially new ones, is there exists a cognitive dissonance where they feel that writing documentation is a tedious, often unnecessary, task. A lot of us feel that if we can understand the code just by looking at it, then so can the next person. Documentation, however, is often the only way another person knows what a function, or application, is doing, or is supposed to do. Not only is it a way to quickly familiarize someone else with the application (necessary parameters, expected results, etc.), but it can also provide insight into why certain decisions were made during development. For instance, why a property is an array, or boolean, etc. Where documentation is especially useful, is when you’re trying to integrate an external API into your application. If well-documented, this can often decrease the overall time spent coding, and also spare you a few headaches.

The people at TypeDoc understand the need for good documentation, and have worked to provide an efficient way to generate documentation for TypeScript projects. With the execution of a simple command, you can generate all the documentation your application will need. TypeDoc parses your TypeScript source code, and generates documentation of your classes, methods, models, etc., based on your code’s comments. It generates documentation, within your project, in the form of HTML web pages, and JSON models. This does two things:

1. It completely eliminates the cognitive dissonance associated with writing documentation, since it’s generated on-the-fly.
2. Encourages developers, especially new ones, to provide meaningful code comments, which is already something that should be practiced.

Sounds good, doesn’t it? Here’s how to implement it (assuming you’re using npm and TypeScript):

(If you’ll be developing regularly in TypeScript, then it might be best to install typedoc globally. You may, however, choose to install it for specific projects only.)

npm install --global typedoc

Run the following command to confirm it has been installed successfully:

typedoc -v

TypeDoc assumes your code is commented following TSDoc standards, which is a doc comment standard for the TypeScript language, proposed by MicroSoft. TSDoc allows you to specify remarks, define params, expected output, and much more. Here’s an example of a basic function, commented in TSDoc standards:

/*** Returns the average of two numbers.** @remarks* This method is part of the {@link core-library#Statistics | Statistics subsystem}.** @param x - The first input number* @param y - The second input number* @returns The arithmetic mean of `x` and `y`** @beta*/function getAverage(x, y) {return (x + y) / 2.0;}

Assuming you’ve developed, and properly-commented your code following the suggested format, execute the following command in your TypeScript project folder to automatically generate the TypeDoc documentation:

typedoc --out docs /src

This will generate a “docs” folder, containing documentation based on your source code.

Here’s an example of TypeDoc documentation:

Go here for the full example.