Angular: Documentation your project with compodoc

One of the best options for documenting an angular project

Angular Compodoc

Introduction

Have you been confused about the documentation projects, especially on the angular? If yes, don’t worry because I had to. Several months ago, I was confused about it and then I search on google and the result is about compodoc. So, I am curious and continue to read about it.

So, in this article, I want to share how to use compodoc for the documentation of the angular project.

Actually, the compodoc is not only for Angular but is also suitable for Nestjs and StencilJs

Prerequisite

1. NodeJs and NPM
2. Angular Project
3. IDE (Vscode, Intellij idea)

Setup Compodoc

In this tutorial, I am using this project for doing the documentation in angular. The name of the branch is angular-compodoc from the communication-data-input-output branch.

GitHub - afifalfiano/angular-tutorial-blogs: All of my short tutorial on medium in this project

After that, add compodoc in the project

Global Installation

npm install -g @compodoc/compodoc

Local Installation

Install with Angular CLI: npm scripts + special tsconfig.doc.json file will be created.

ng add @compodoc/compodoc

or

npm install --save-dev @compodoc/compodoc

Then, on tsconfig.doc.json you can add or remove files that you want to documentation. By default, the config compodoc will include any files with extension .ts and exclude any files with extension .spec.ts

{"include":["src/**/*.ts"],"exclude":["src/**/*.spec.ts"]}

Then, open your package.json

  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test",
    "compodoc:build": "compodoc -p tsconfig.doc.json",
    "compodoc:build-and-serve": "compodoc -p tsconfig.doc.json -s",
    "compodoc:serve": "compodoc -s"
  },

The package.json automatically added some script to run the compodoc. Run this command to show the compodoc result.

npm run compodoc:build-and-serve

Once you run the command, you will see this thing on your CLI.

CLI Compodoc

The compodoc will generate all components, config, interfaces, and many things depending on compodoc config. After the generate is completed, it will create a new folder with name documentation.

By default, we can open http://127.0.0.1:8080 to see the documentation of our project.

First Look Compodoc

That is really awesome, We can see this thing with a small effort.

Let’s see what looks like the component child in the documentation.

Demo Compodoc

Improving Documentation

Actually, you have finished adding documentation to your Angular project. But, I think we can improve with add descriptions on functions or variables. For example, I try to improve documentation on the component Child.

I’m using jsDoc shortcut on the top of the function and auto-generate like this, just need a little adjustment

import { Component, Input, Output, EventEmitter } from '@angular/core';

/**
 * ChildComponent is component to show data from parent and emit data to parent.
 */
@Component({
  selector: 'app-child',
  templateUrl: './child.component.html',
  styleUrls: ['./child.component.scss']
})
export class ChildComponent {
  /**Description: Variable to get value from parent component */
  @Input() name!: string;

  /**Description:  Variable to assign value of two way data binding on input text */
  feedback = '';

  /**Description: Variable to emit data from child to parent */
  @Output() childToParent: EventEmitter<string> = new EventEmitter<string>();

  /**
   * Description: onSendFeedback is function to emit data from child component into parent component}
   * @param {string} feedback
   * @returns {void}
   * @memberof ChildComponent
   */
  onSendFeedback(feedback: string) {
    this.childToParent.emit(feedback);
  }
}

I know that looks a little dirty, but for complex logic sometimes you need some clue besides the names of functions and variables. After we add some comments on the code, the documentation will be like this.

Demo Compodoc Comment

The reason why in our code we use Description instead of @description is because compodoc only wants to return or generate the description if we use Description. It’s your choice if you want Description or @description

Conclusion

Hopefully, this article will answer you're confused about how to documentation the angular project. I think you can search for more combinations about the jsDoc with compodoc.

We need to add documentation to our project to make sure another developer easily understands our code and maintains it. Because we never know how long we will write code in a company.

The project has already been pushed to this branch

GitHub - afifalfiano/angular-tutorial-blogs at angular-compodoc

If any feedback or suggestion for me, just reply to this article or email to afifalfiano2@gmail.com. Thank you, guys.

References

Compodoc - The missing documentation tool for your Angular application

Angular

#Frontend #Angular #Compodoc #AngularTutorial #Documentation