Documenting software is hard. Not only that, maintaining software documentation is even more complicated and often forgotten.
What’s the solution, then? What about using an automated solution that:
- Generates documentation from code comments and does not require a Wiki or any third-party software.
- Generates said documentation automatically and can be part of your build process.
- Gives metrics and feedback to developers to encourage them to write more documentation.
Such a solution exists. It’s called Compodoc. Compodoc can generate a Javadoc-like website from all the comments written in your application (you can see an example of such documentation here):
Compodoc can be installed globally with npm:
npm install -g @compodoc/compodocCode language: CSS (css)Or you can add it locally to a single Angular project by running the ng add schematic in your project folder:
ng add @compodoc/compodocCode language: CSS (css)Then you can create a config file to decide which files to include in the documentation (for instance, you might want to exclude test, and Compodoc is ready to run with a single command:
npx compodoc -p tsconfig.doc.jsonCode language: CSS (css)The above command creates a static HTML website documenting your entire application with all modules/components/pipes/directives/services.
My favorite feature is the documentation coverage statistics that show which parts of the application are well-documented and which are not, using a report similar to test coverage reports that developers are familiar with.
