Documentation Tool for Angular Projects

“Documenting your code is as important as writing readable code. As the application grows, new developers who join the project might find it difficult to understand certain aspects of the application. If an application is well commented and documented, it becomes easier for them to understand key aspects, track changes, and improve the quality of the application.”

Documentation in Angular

When working with plain JS applications, you would use documentation tools specially designed for Javascript. One of the common tools is, for example, JSDoc. It is similar to JavaDoc tool used with Java which can generate documentation based on special comments, which are present directly in the code.

However, when working with a framework such as Angular, it is handy to have something more powerful. It is because you need not only to document generic JS code, but you would also want to take into consideration specifics of the framework.

compodoc

CompoDoc is here to solve our problem. It is focused on Angular apps especially giving you a much more tailored solution. It will give you a way to document your code in a presentable format.

Getting started

In your Angular project’s root, run following command:

npm install --save-dev @compodoc/compodoc

This will install compodoc as a dev dependency of your project.

Add scripts in package.json as following:

"scripts": { 
     ....
    "generate-docs": "compodoc -p src/tsconfig.app.json",
    "serve-docs" : compodoc -s src/tsconfig.app.json",
 }

Note : You can specify a different tsconfig file if you have it with another name or at another location.

To generate documentation of your project, run the following command:

npm run generate-docs

Generated documentation can be seen by launching index.html from the generated documentation folder in your root project folder.

You can also generate and serve documentation on a local server, i.e. http://127.0.0.1:8080

npm run serve-docs

Congratulations.. You are done!!

Sample Outputs

Compodoc understands that your app is an Angular application. That means it understands all the concepts such as components, pipes, or directives. Below, you can see the documentation generated for a component.

Since Angular applications consist of modules, it is best to document them and their relationships. Compodoc allows you to do that. You can even see the relationships of each module in a nice diagram.

Documentation Coverage

One more feature worth mentioning is a documentation coverage, which allows you to measure how well commented your application is.

You can check sample Compodoc generated documentation — try the official live demo.

In order to get more details about Compodoc you can visit the getting started guide.

I would like to thank the creators of this awesome tool:

compodoc/compodoc