feat: Add detailed JSDoc comments to CoreController, CoreModule, and CoreService for improved documentation

Author: tacxou

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

@@ -1,9 +1,36 @@
-import { Controller } from '@nestjs/common';
-import { CoreService } from './core.service';
-import { ApiTags } from '@nestjs/swagger';
+import { Controller } from '@nestjs/common'
+import { CoreService } from './core.service'
+import { ApiTags } from '@nestjs/swagger'
 
+/**
+ * Contrôleur principal du module Core.
+ *
+ * Ce contrôleur sert de point d'entrée pour les endpoints API du module Core.
+ * Le module Core regroupe les fonctionnalités essentielles du système telles que
+ * la gestion des agents, des audits, de l'authentification, des backends, etc.
+ *
+ * @class CoreController
+ *
+ * @description
+ * Le contrôleur Core peut exposer des endpoints globaux ou transversaux qui ne
+ * relèvent pas d'un sous-module spécifique. Les fonctionnalités métier sont
+ * généralement déléguées aux sous-contrôleurs spécialisés :
+ * - AgentsController : Gestion des agents
+ * - AuditsController : Consultation des audits
+ * - AuthController : Authentification et autorisation
+ * - BackendsController : Gestion des backends
+ * - etc.
+ *
+ * Ce contrôleur reste disponible pour des opérations générales au niveau du module Core
+ * ou pour servir de facade à des fonctionnalités transversales.
+ */
 @ApiTags('core')
 @Controller('core')
 export class CoreController {
-  public constructor(private readonly _service: CoreService) {}
+  /**
+   * Constructeur du contrôleur CoreController.
+   * 
+   * @param {CoreService} _service - Le service Core pour la logique métier
+   */
+  public constructor(private readonly _service: CoreService) { }
 }

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

@@ -1,18 +1,45 @@
-import { DynamicModule, Module } from '@nestjs/common';
-import { RouterModule } from '@nestjs/core';
-import { AgentsModule } from './agents/agents.module';
-import { AuthModule } from './auth/auth.module';
-import { BackendsModule } from './backends/backends.module';
-import { CoreController } from './core.controller';
-import { CoreService } from './core.service';
-import { JobsModule } from './jobs/jobs.module';
-import { KeyringsModule } from './keyrings/keyrings.module';
-import { LoggerModule } from './logger/logger.module';
-import { TasksModule } from './tasks/tasks.module';
-import { FilestorageModule } from './filestorage/filestorage.module';
-import { AuditsModule } from './audits/audits.module';
-import { HealthModule } from './health/health.module';
+import { DynamicModule, Module } from '@nestjs/common'
+import { RouterModule } from '@nestjs/core'
+import { AgentsModule } from './agents/agents.module'
+import { AuthModule } from './auth/auth.module'
+import { BackendsModule } from './backends/backends.module'
+import { CoreController } from './core.controller'
+import { CoreService } from './core.service'
+import { JobsModule } from './jobs/jobs.module'
+import { KeyringsModule } from './keyrings/keyrings.module'
+import { LoggerModule } from './logger/logger.module'
+import { TasksModule } from './tasks/tasks.module'
+import { FilestorageModule } from './filestorage/filestorage.module'
+import { AuditsModule } from './audits/audits.module'
+import { HealthModule } from './health/health.module'
 
+/**
+ * Module Core - Fonctionnalités essentielles du système.
+ *
+ * Ce module regroupe tous les sous-modules et fonctionnalités de base nécessaires
+ * au fonctionnement de l'orchestrateur Sesame. Il agit comme un hub central qui
+ * organise et expose les API des différents composants du système.
+ *
+ * @module CoreModule
+ *
+ * @description
+ * Sous-modules intégrés :
+ * - **AuthModule** : Authentification et autorisation des agents
+ * - **AgentsModule** : Gestion des agents (utilisateurs/systèmes)
+ * - **AuditsModule** : Système d'audit et d'historique des modifications
+ * - **BackendsModule** : Gestion des backends de connexion
+ * - **LoggerModule** : Système de logging centralisé
+ * - **KeyringsModule** : Gestion des clés cryptographiques
+ * - **JobsModule** : Gestion des tâches asynchrones et files d'attente
+ * - **TasksModule** : Gestion des tâches planifiées
+ * - **FilestorageModule** : Stockage et gestion de fichiers
+ * - **HealthModule** : Vérification de l'état de santé du système
+ *
+ * Architecture :
+ * - Tous les sous-modules sont automatiquement préfixés avec '/core' dans les routes
+ * - Utilise le RouterModule pour organiser la hiérarchie des routes
+ * - Expose un service CoreService pour la logique transversale
+ */
 @Module({
   imports: [
     AuthModule,
@@ -30,6 +57,21 @@ import { HealthModule } from './health/health.module';
   controllers: [CoreController],
 })
 export class CoreModule {
+  /**
+   * Enregistre le module Core en mode dynamique avec le routage configuré.
+   *
+   * Cette méthode configure automatiquement le préfixe '/core' pour tous les
+   * sous-modules importés, créant une hiérarchie de routes cohérente.
+   *
+   * @static
+   * @returns {DynamicModule} Le module configuré avec le RouterModule
+   *
+   * @description
+   * La méthode utilise les métadonnées de réflexion pour récupérer dynamiquement
+   * tous les modules importés et les enregistrer comme enfants de la route '/core'.
+   * Cela permet d'ajouter ou retirer des sous-modules sans modifier la configuration
+   * de routage manuellement.
+   */
   public static register(): DynamicModule {
     return {
       module: this,

apps/api/src/core/core.service.ts

@@ -1,6 +1,24 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable } from '@nestjs/common'
+import { AbstractService } from '~/_common/abstracts/abstract.service'
 
+/**
+ * Service principal du module Core.
+ *
+ * Ce service fournit la logique métier transversale pour le module Core.
+ * Il peut contenir des fonctionnalités communes à plusieurs sous-modules
+ * ou des opérations qui nécessitent la coordination de plusieurs services.
+ *
+ * @class CoreService
+ * @extends {AbstractService}
+ */
 @Injectable()
-export class CoreService {
-  public constructor() {}
+export class CoreService extends AbstractService {
+  /**
+   * Constructeur du service CoreService.
+   *
+   * @constructor
+   */
+  public constructor() {
+    super()
+  }
 }