26-3 Documenter les composants

La documentation d'un composant est très similaire à celle d'une classe conventionnelle.

Composant de page

src/app/features/projets/pages/projet-detail.ts

/**
 * Composant de page affichant le détail d'un projet.
 */
@Component({
  selector: 'app-projet-detail',
  imports: [
    RouterLink,
    IssuesListe
  ],
  template: `
    @if (projet) {
      <div class="row">
        <div class="col-lg-8">
          <h1>{{projet.nom}}</h1>
        </div>
        <div class="col-lg-4 d-flex align-items-center justify-content-lg-end">
          <a class="btn btn-secondary" [routerLink]="['/projets', projet.id, 'modifier']">Modifier</a>
        </div>
      </div>
      <div class="row mt-3">
        <div class="col">
          <p>{{projet.description}}</p>
        </div>
      </div>
      <div class="row mt-3">
        <div class="col">
          <app-issues-liste [projetId]="projet.id"></app-issues-liste>
        </div>
      </div>
    }
  `,
  host: {
    class: 'custom-class'
  },
  styles: ``
})
export class ProjetDetail implements OnInit {
  /**
   * Identifiant du projet à charger
   * @type {number | null}
   * @protected
   */
  protected id: number | null = null;

  /**
   * Le projet, après voir été récupéré de l'API
   * @type {Projet | null}
   * @protected
   */
  protected projet: Projet | null = null;

  constructor(private route: ActivatedRoute,
              private projetService: ProjetService) {
  }

  async ngOnInit(): Promise<void> {
    this.route.paramMap.subscribe(async (params) => {
      const routeParam = params.get('id');
      if(routeParam){
        this.id = +routeParam;
        await this.chargerProjet();
      }
    });
  }

  /**
   * Charge le projet à afficher et redirige l'utilisateur
   * s'il n'existe pas.
   * @returns {Promise<void>}
   */
  async chargerProjet() {
    if(this.id) {
      try {
        this.projet = await this.projetService.obtenir(this.id);
      } catch (error) {
        if(error instanceof NotFoundError) {
          // traiter l'erreur comme une erreur 404 et rediriger vers une page de type 404
        } else {
          // traiter l'erreur générique
        }
      }
    }
  }
}

info

Vous n'avez pas à documenter le constructeur, à moins que ce dernier utilise des dépendances très peu fréquentes ou encore effectue une logique particulière. Le constructeur est utilisé principalement pour l'injection de dépendance en Angular, donc son comportement et ses paramètres sont généralement très bien compris.

Idem pour ngOnInit qui est une fonction du cycle de vie d'une composante normalement bien connue d'un développeur Angular.

Composant réutilisable

Un composant réutilisable peut demander un peu plus de détails, incluant un exemple d'utilisation puisque celui-ci sera utilisé directement dans d'autres composants et prend bien souvent des paramètres en entrée.

src/app/features/projets/components/projets-liste.ts

/**
 * Affiche une liste de projets.
 * @example
 * <app-projets-liste [projets]="projets"></app-projets-liste>
 */
@Component({
  selector: 'app-projets-liste',

  //...