Document your Typescript Project in 5 mins - typedoc

Introduction

typedoc is a fairly simple and easy library to setup, and its benefits are in how you document your codebase. The library itself is also really popular, and commands for adding comments are pretty straightforward. Most of the type inference is done by typescript itself, which gives you fewer things to worry about.

Official Documentation

If instead or in addition to this article, you wanted to go to the offical website (which is highly recommended) click here

Installation

To install the typedoc package:

npm install typedoc --save-dev

You can verify if it works by:

$ npx typedoc --version

TypeDoc 0.20.0
Using TypeScript 4.1.2 from /home/gerrit/typedoc/node_modules/typescript/lib

Usage

Now that we have installed the library, we can generate a documentation to get the gist of how it works.

To keep things simple, this is what you need to care about:

1. Where the generated documentation should be outputted
2. Which source files should be used

We specify the output directory using the --out parameter followed by the path to output directory.
Anything declared without a flag 'eg, --out' will be treated as a source file and will be parsed for generating documentation
We can run this command to generate a documentation:

$ typedoc --out docs/ src/app/

Instead of the src/app/ folder you can also point to your applications entry point, which for a react project would be your src/index.ts file. Typedoc treats file and folder locations differently. If you point to a folder it will treat all files inside that folder as individual entry points. If you point to a file, which typedoc says should be your applications entry point, it will generate documentation for the module that file exports.

Heres how the generated document looked for my project

When you open the index.html file for your documentation, this is what is displayed, if your project has a readme.md, you'll be greeted to a preview of it. The explorer menu on the right lists all the modules typedoc found and generated documentation for in your project.

I was running into issues generating a documentation when pointing to what is supposed to be my projects entry point. I think this might be due to the fact that the project I am generating this for, is an Angular project, I am using a source folder instead of an entry point file, because in Angular entry points are treated differently. Angular instead provides a compilation of files, instead of a fixed entry point. see here.

How the documentation is displayed

This part is fairly straightforward, and ill illustrate using an example component.

This is a preview of the documentation typedoc will generate for just 1 component, which in this case is an example-component I created with some basic properties and methods.

I havent commented anything, but luckily for us, typedoc generates a barebones documentation for our functions as well.

All of this has been generated by typedoc automatically!

Adding documentation comments

Now that we have an idea of how it works, we will move on to the final section, adding comments, and utilizing some basic typedoc tags namely @param and @return.
I'll add some nice little descriptions to my greetings function

I run the command to generate the documentation again:

$ npx typedoc --out docs src/app/

And if we navigate to our example component again we can see the updated documentation

Isn't this great? that's all it took to generate a pretty-ish but useful documentation.

typedoc uses markdown for generating its documentation, so I guess if you wanted to you could even add a heading tag in a comment and get this

Conclusion

You should now have some idea about how typedoc works, how to generate a basic documentation and how to add your own code comments. More than that however, I hope this makes you more willing to add documentation your codebase.