feat: Add detailed JSDoc comments to HealthController and HealthModule for improved documentation

Author: tacxou

apps/api/src/core/health/health.controller.ts

@@ -4,13 +4,45 @@ import { ApiTags } from '@nestjs/swagger'
 import { HealthCheckService, HttpHealthIndicator, HealthCheck, DiskHealthIndicator, MemoryHealthIndicator, MongooseHealthIndicator, HealthCheckResult } from '@nestjs/terminus'
 import { Public } from '~/_common/decorators/public.decorator'
 
+/**
+ * Multiplicateur pour convertir les octets en mégaoctets.
+ * @constant {number}
+ */
 const MEMORY_MULTIPLIER = 1024 * 1024
-const DISK_MULTIPLIER = 1024 * 1024 * 1024
 
+/**
+ * Contrôleur pour la vérification de l'état de santé du système.
+ *
+ * Ce contrôleur expose des endpoints de health check permettant de surveiller
+ * l'état de santé de l'application et de ses dépendances. Il utilise NestJS Terminus
+ * pour vérifier différents indicateurs de santé.
+ *
+ * @class HealthController
+ *
+ * @description
+ * Indicateurs de santé vérifiés :
+ * - **Mongoose** : Connectivité à la base de données MongoDB
+ * - **HTTP** : Connectivité réseau externe (test avec GitHub)
+ * - **Disk** : Utilisation du disque (seuil à 95%)
+ * - **Memory Heap** : Utilisation de la mémoire heap (seuil à 512 MB)
+ * - **Memory RSS** : Utilisation de la mémoire RSS (seuil à 512 MB)
+ *
+ * Le endpoint est public (pas d'authentification requise) pour permettre
+ * aux systèmes de monitoring externes de vérifier l'état du service.
+ */
 @Public()
 @ApiTags('core/health')
 @Controller('health')
 export class HealthController {
+  /**
+   * Constructeur du contrôleur HealthController.
+   *
+   * @param {HealthCheckService} health - Service de vérification de santé
+   * @param {MongooseHealthIndicator} mongoose - Indicateur de santé MongoDB
+   * @param {HttpHealthIndicator} http - Indicateur de santé HTTP
+   * @param {DiskHealthIndicator} disk - Indicateur de santé du disque
+   * @param {MemoryHealthIndicator} memory - Indicateur de santé de la mémoire
+   */
   public constructor(
     private readonly health: HealthCheckService,
 
@@ -20,6 +52,15 @@ export class HealthController {
     private readonly memory: MemoryHealthIndicator,
   ) { }
 
+  /**
+   * Endpoint de vérification de l'état de santé du système.
+   *
+   * Exécute une série de vérifications pour déterminer si l'application
+   * et ses dépendances sont opérationnelles. Retourne un statut global
+   * ainsi que le détail de chaque indicateur.
+   *
+   * @returns {Promise<HealthCheckResult>} Résultat complet du health check
+   */
   @Get()
   @HealthCheck()
   public async check(): Promise<HealthCheckResult> {

apps/api/src/core/health/health.module.ts

@@ -1,8 +1,34 @@
-import { Module } from '@nestjs/common';
-import { TerminusModule } from '@nestjs/terminus';
-import { HttpModule } from '@nestjs/axios';
-import { HealthController } from './health.controller';
+import { Module } from '@nestjs/common'
+import { TerminusModule } from '@nestjs/terminus'
+import { HttpModule } from '@nestjs/axios'
+import { HealthController } from './health.controller'
 
+/**
+ * Module de vérification de l'état de santé du système.
+ *
+ * Ce module configure et expose les endpoints de health check permettant de surveiller
+ * l'état de santé de l'application, de ses dépendances et de ses ressources système.
+ * Il utilise NestJS Terminus pour fournir des indicateurs standardisés de santé.
+ *
+ * @module HealthModule
+ *
+ * @description
+ * Le module configure :
+ * - **TerminusModule** : Framework de health check de NestJS avec affichage formaté des erreurs
+ * - **HttpModule** : Module HTTP pour les vérifications de connectivité externe
+ * - **HealthController** : Contrôleur exposant les endpoints de health check
+ *
+ * Fonctionnalités de monitoring :
+ * - Vérification de la connectivité à la base de données MongoDB
+ * - Vérification de la connectivité réseau externe
+ * - Surveillance de l'utilisation du disque
+ * - Surveillance de la consommation mémoire (heap et RSS)
+ *
+ * Utilisation :
+ * - Les endpoints sont publics (pas d'authentification) pour permettre le monitoring externe
+ * - Compatibles avec les systèmes de monitoring comme Kubernetes liveness/readiness probes
+ * - Format de réponse standardisé compatible avec les outils de monitoring
+ */
 @Module({
   imports: [
     TerminusModule.forRoot({