Image for post
Image for post
Photo by Sean Lim on Unsplash

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.)

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

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:

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:

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

Here’s an example of TypeDoc documentation:

Image for post
Image for post
TypeDoc-generated documentation page

Go here for the full example.

Interested in Computer Science, education and world domination.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store