Documentation en TypeScript : comment écrire du code qui parle de lui-même

Introduction : pourquoi la documentation n'est pas une corvée ennuyeuse, mais un super-pouvoir

Imaginez : vous revenez à votre projet six mois plus tard. Vous ouvrez le fichier contenant la logique d'authentification — et vous voyez une mer de code TypeScript. Les types sont là, les interfaces sont définies, mais que fait cette fonction ? Pourquoi le paramètre s'appelle opts et quels sont ses champs ? Cela vous dit quelque chose ?

La documentation en TypeScript n'est pas simplement des « commentaires pour la forme ». C'est un outil qui transforme votre code en une histoire compréhensible. Une bonne documentation fait gagner des heures de débogage, accélère l'intégration des nouveaux venus et rend votre API conviviale. Dans cet article, nous allons passer en revue les meilleures pratiques de documentation pour les projets TypeScript : des commentaires JSDoc de base à la génération avancée de documentation avec TypeDoc. C'est parti !

1. JSDoc et TSDoc : le fondement de votre documentation

TypeScript a hérité de JavaScript le format populaire JSDoc, puis la communauté a développé TSDoc — une syntaxe standardisée pour TypeScript. Si vous écrivez une bibliothèque ou une API, TSDoc est votre choix. Il est plus strict, mieux intégré avec les éditeurs et les générateurs de documentation.

Balises TSDoc de base

Voici le minimum que tout développeur devrait connaître :

\n
• @param — description du paramètre d'une fonction
\n
• @returns — ce que retourne la fonction
\n
• @throws — les exceptions qu'elle peut lever
\n
• @example — exemple d'utilisation
\n
• @deprecated — marquage de code obsolète
\n

/**\n * Calcule la réduction sur un produit en tenant compte du code promo.\n * \n * @param price - Prix initial du produit (doit être supérieur à 0)\n * @param discountPercent - Pourcentage de réduction (de 0 à 100)\n * @param promoCode - Code promo pouvant augmenter la réduction\n * @returns Prix final après application de la réduction\n * @throws {Error} Si le prix ou le pourcentage sont incorrects\n * \n * @example\n * // Exemple : réduction de 20% sur un produit à 1000 roubles\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n  price: number,\n  discountPercent: number,\n  promoCode?: string\n): number {\n  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n    throw new Error('Paramètres incorrects');\n  }\n  \n  let discount = discountPercent;\n  if (promoCode === 'SUMMER') {\n    discount += 10; // réduction supplémentaire\n  }\n  \n  return price * (1 - discount / 100);\n}\n

Conseil : Décrivez toujours les cas limites. Si un paramètre peut être undefined, indiquez-le dans la description. Les types TypeScript, c'est bien, mais le langage humain ajoute du contexte.

2. Documentez les types et les interfaces

L'une des principales fonctionnalités de TypeScript est son puissant système de types. Mais même le type le plus strict n'expliquera pas le rôle d'un champ. Documentez les interfaces aussi minutieusement que les fonctions.

/**\n * Configuration pour la connexion à une API météo externe.\n */\ninterface WeatherApiConfig {\n  /** URL de base de l'API (ex : https://api.weather.com) */\n  baseUrl: string;\n  \n  /** Clé d'authentification obtenue auprès du fournisseur */\n  apiKey: string;\n  \n  /** \n   * Nombre de secondes d'attente de la réponse du serveur.\n   * Par défaut 5 secondes.\n   */\n  timeout?: number;\n  \n  /**\n   * Version de l'API. Si non spécifiée, la dernière version stable est utilisée.\n   * @deprecated Utilisez le champ `version` dans l'URL\n   */\n  apiVersion?: string;\n}\n

Remarquez : pour timeout, nous avons indiqué la valeur par défaut directement dans le commentaire. Cela évite au développeur d'avoir à fouiller dans le code source ou les tests.

3. Génération de documentation : transformer les commentaires en site web

Écrire des commentaires n'est que la moitié du travail. Il faut savoir les transformer en une documentation pratique. Pour TypeScript, le meilleur outil est TypeDoc. Il analyse vos commentaires TSDoc