Aller au contenu principal

Génération de documentation de code dans Cursor : guide complet

Documentation de code dans Cursor

Une bonne documentation est le pont entre le code et les personnes qui l'utilisent — qu'il s'agisse de développeurs, de consommateurs d'API ou de vous-même dans le futur. La documentation couvre les commentaires en ligne, les références d'API, les annotations de type et les guides autonomes. Cursor, avec son assistant IA et son riche écosystème d'extensions, est un environnement exceptionnel pour créer et maintenir la documentation. Il peut générer des commentaires JSDoc et TSDoc à partir du code, scaffolder des spécifications OpenAPI et exporter du Markdown soigné à partir de votre base de code existante.

Ce guide couvre le workflow complet de documentation dans Cursor : écriture de JSDoc et TSDoc, génération de spécifications OpenAPI/Swagger, exploitation de l'IA pour la génération de documentation et export de livrables Markdown. Que vous documentiez une bibliothèque, un service interne ou une API publique, les techniques ci-dessous vous aideront à produire une documentation claire, précise et maintenable.

Configuration des outils de documentation dans Cursor​

Extensions essentielles​

Installez ces extensions pour booster le travail de documentation dans Cursor :

  1. Markdown All in One — raccourcis clavier, génération de table des matières et édition de listes pour les fichiers .md.
  2. Markdown Preview Enhanced — aperçu en direct avec formules mathématiques, diagrammes et exécution de code.
  3. Docs View — aperçu Markdown côte à côte qui se met à jour pendant la saisie.
  4. OpenAPI (Swagger) Editor — validation de schéma et aperçu pour OpenAPI YAML/JSON.
  5. Prettier — formatage cohérent pour Markdown et YAML.
astuce

L'extension OpenAPI fournit un volet d'aperçu en direct qui rend votre openapi.yaml en une page de documentation API interactive, similaire à Redoc ou Swagger UI. Cela vous permet d'itérer sur votre spec et de voir le résultat instantanément sans quitter Cursor.

Structure de projet pour la documentation​

Une disposition de projet adaptée à la documentation :

project/
  ├── src/
  │   ├── index.ts
  │   ├── utils/
  │   └── handlers/
  ├── docs/
  │   ├── api/
  │   │   ├── openapi.yaml
  │   │   └── schemas/
  │   ├── guides/
  │   └── changelog.md
  ├── README.md
  └── tsconfig.json

JSDoc : documenter le code JavaScript​

Syntaxe JSDoc de base​

JSDoc est le standard pour documenter le code JavaScript. L'IA de Cursor génère automatiquement des commentaires JSDoc à partir des signatures de fonction.

/**
 * Calculates the total price of items in a cart, applying any discount.
 *
 * @param {Array<{price: number, quantity: number}>} items - The cart items.
 * @param {number} [discount=0] - Optional discount rate between 0 and 1.
 * @returns {number} The total price after discount.
 * @throws {Error} If any item has a negative price.
 * @example
 * const total = calculateTotal([
 *   { price: 10, quantity: 2 },
 *   { price: 5, quantity: 1 },
 * ], 0.1);
 * // returns 22.5
 */
function calculateTotal(items, discount = 0) {
  if (items.some((item) => item.price < 0)) {
    throw new Error('Item price cannot be negative');
  }
  const subtotal = items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );
  return subtotal * (1 - discount);
}
astuce

L'IntelliSense de Cursor lit les commentaires JSDoc et les affiche dans les infobulles de survol, les suggestions d'autocomplétion et l'aide à la signature. Un JSDoc bien écrit fait qu'un projet JavaScript semble aussi sûr en types que TypeScript pour les consommateurs.

Documenter les classes et modules​

/**
 * Represents a shopping cart.
 *
 * @class Cart
 */
class Cart {
  /**
   * @private
   * @type {Array<{id: string, name: string, price: number, qty: number}>}
   */
  #items = [];

  /**
   * Adds a product to the cart.
   *
   * @param {string} id - Unique product identifier.
   * @param {string} name - Product display name.
   * @param {number} price - Unit price in USD.
   * @param {number} [qty=1] - Quantity to add.
   * @returns {void}
   * @fires Cart#itemAdded
   */
  add(id, name, price, qty = 1) {
    this.#items.push({ id, name, price, qty });
    /**
     * Item added event.
     *
     * @event Cart#itemAdded
     * @type {object}
     * @property {string} id - The product ID.
     * @property {number} qty - The quantity added.
     */
    this.emit('itemAdded', { id, qty });
  }

  /**
   * Returns the total value of the cart.
   *
   * @returns {number} Total price of all items.
   */
  total() {
    return this.#items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }
}

Définitions de types personnalisés​

Définissez des types réutilisables avec @typedef :

/**
 * @typedef {Object} Product
 * @property {string} id - Unique identifier.
 * @property {string} name - Display name.
 * @property {number} price - Unit price in USD.
 * @property {string[]} [tags] - Optional categorization tags.
 */

/**
 * @typedef {Object} CartItem
 * @property {Product} product - The product reference.
 * @property {number} qty - Quantity in the cart.
 */

/**
 * Creates a cart item from a product.
 * @param {Product} product - The product.
 * @param {number} qty - The quantity.
 * @returns {CartItem}
 */
function toCartItem(product, qty) {
  return { product, qty };
}
attention

Les définitions @typedef de JSDoc doivent apparaître avant d'être référencées. Placez les types partagés dans un seul fichier types.js et utilisez @see ou les imports pour les référencer entre modules. Un placement incohérent fait que l'IntelliSense affiche « any » au lieu du type correct.

TSDoc : documenter le code TypeScript​

TSDoc vs JSDoc​

TSDoc est une variante de JSDoc standardisée pour TypeScript. Elle utilise la même syntaxe de commentaire mais se concentre sur la description des types déjà déclarés dans les signatures TypeScript, omettant donc les annotations de type @param redondantes.

/**
 * Calculates the total price of items in a cart, applying any discount.
 *
 * @param items - The cart items.
 * @param discount - Optional discount rate between 0 and 1. Default is 0.
 * @returns The total price after discount.
 * @throws {Error} If any item has a negative price.
 *
 * @example
 * ```ts
 * const total = calculateTotal(
 *   [{ price: 10, quantity: 2 }, { price: 5, quantity: 1 }],
 *   0.1
 * );
 * ```
 */
function calculateTotal(
  items: Array<{ price: number; quantity: number }>,
  discount = 0
): number {
  if (items.some((item) => item.price < 0)) {
    throw new Error('Item price cannot be negative');
  }
  const subtotal = items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );
  return subtotal * (1 - discount);
}
astuce

En TypeScript, les types de paramètres sont déjà dans la signature. Les répéter dans @param comme {number} est redondant et crée de la dérive. Utilisez le style TSDoc — décrivez le sens, pas le type.

Documenter les interfaces et types​

/**
 * Configuration options for the HTTP client.
 */
interface HttpClientOptions {
  /** Base URL prepended to all relative request paths. */
  baseUrl: string;

  /** Default timeout in milliseconds. Defaults to 30000. */
  timeout?: number;

  /** Maximum number of automatic retries on 5xx responses. */
  retries?: number;

  /** Custom headers applied to every request. */
  headers?: Record<string, string>;
}

/**
 * A typed HTTP client with retry and timeout support.
 *
 * @example
 * ```ts
 * const client = new HttpClient({ baseUrl: 'https://api.example.com' });
 * const data = await client.get<User>('/users/1');
 * ```
 */
class HttpClient {
  /**
   * @param options - Configuration for the client.
   */
  constructor(private options: HttpClientOptions) {}

  /**
   * Performs a GET request.
   *
   * @typeParam T - The expected response type.
   * @param path - The request path, relative to baseUrl.
   * @returns A promise resolving to the parsed response body.
   * @throws {HttpError} On non-2xx responses after retries.
   */
  async get<T>(path: string): Promise<T> {
    // implementation
    return {} as T;
  }
}

Utilisation de l'extension TSDoc​

Installez l'extension TSDoc pour le support des snippets et la validation. Elle fournit :

  • Des snippets pour @param, @returns, @throws, @example.
  • Du linting pour les tags TSDoc malformés.
  • La génération automatique de stubs de commentaire à partir des signatures TypeScript.
astuce

Tapez les caractères /** au-dessus d'une déclaration de fonction et appuyez sur Entrée. Cursor (propulsé par le serveur de langage TypeScript) génère automatiquement un stub TSDoc avec des espaces réservés @param et @returns pour chaque paramètre.

OpenAPI et Swagger​

Qu'est-ce qu'OpenAPI ?​

OpenAPI (anciennement Swagger) est la spécification standard de l'industrie pour décrire les API REST. Un seul fichier openapi.yaml documente chaque endpoint, corps de requête, schéma de réponse et méthode d'authentification, permettant la génération automatique de SDK clients, de docs interactives et de tests de contrat.

Écriture d'une spécification OpenAPI​

# docs/api/openapi.yaml
openapi: 3.1.0
info:
  title: User Service API
  version: 1.0.0
  description: |
    REST API for managing users in the application.
    Supports CRUD operations and role-based access control.
  contact:
    name: API Support
    email: [email protected]
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Display name.
        email:
          type: string
          format: email
          description: Email address.
        age:
          type: integer
          minimum: 0
          description: User age.
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp of creation.

    CreateUserRequest:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        age:
          type: integer
          minimum: 0

    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string

paths:
  /users:
    get:
      summary: List users
      description: Returns a paginated list of users.
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: A paginated list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
                  page:
                    type: integer
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Create a user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found.

    delete:
      summary: Delete a user
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: User deleted.
        '403':
          description: Forbidden.
astuce

L'extension OpenAPI dans Cursor rend ce YAML en un aperçu interactif. Cliquez sur n'importe quel endpoint pour développer ses paramètres et réponses, et utilisez le bouton « Try it out » pour envoyer des requêtes en direct directement depuis l'éditeur.

Génération d'OpenAPI à partir du code​

Pour les applications Express, utilisez swagger-jsdoc pour extraire OpenAPI des annotations JSDoc :

npm install swagger-jsdoc swagger-ui-express
// src/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc';
import { writeFileSync } from 'fs';

const options = {
  definition: {
    openapi: '3.1.0',
    info: {
      title: 'User Service API',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes/*.ts'],
};

const spec = swaggerJsdoc(options);
writeFileSync('./docs/api/openapi.json', JSON.stringify(spec, null, 2));

Annotez vos routes :

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: The user.
 */
router.get('/users/:id', getUserById);
attention

La génération OpenAPI code-first dérive de l'implémentation réelle lorsque les développeurs modifient les routes sans mettre à jour les annotations. Exécutez un test de contrat (avec Dredd ou Schemathesis) en CI pour détecter la dérive tôt.

Validation des specs OpenAPI​

Installez @redocly/cli pour le linting et le bundling :

npm install -D @redocly/cli
npx redocly lint docs/api/openapi.yaml

Ajoutez une étape CI :

- name: Validate OpenAPI spec
  run: npx redocly lint docs/api/openapi.yaml

Génération de documentation assistée par IA​

Génération de JSDoc et TSDoc à partir du code​

L'IA de Cursor excelle à produire des commentaires de documentation à partir de code existant. Sélectionnez une fonction, appuyez sur Ctrl+K et saisissez :

Generate TSDoc for this function. Include @param descriptions,
@returns, @throws, and an @example with a realistic code snippet.

Cursor lit la signature et produit un commentaire complet. Vérifiez la précision de la sortie, puis acceptez.

astuce

Pour la génération en masse, sélectionnez un fichier entier et demandez à Cursor « d'ajouter des commentaires TSDoc à chaque fonction et classe exportée. » L'IA traite chaque déclaration à tour de rôle, vous faisant gagner des minutes de saisie manuelle.

Génération d'OpenAPI à partir de fichiers de routes​

Saisissez un prompt dans Cursor avec un fichier de route ouvert :

Generate an OpenAPI 3.1 specification fragment for all the routes in
this file. Include request bodies, response schemas, query parameters,
and security requirements. Output as YAML.

L'IA analyse chaque gestionnaire de route et produit un objet de chemin OpenAPI correspondant. Fusionnez la sortie dans votre openapi.yaml principal.

Documenter une logique complexe​

Pour les algorithmes au comportement non évident, demandez à Cursor d'écrire des commentaires explicatifs :

Explain the retry-with-exponential-backoff logic in this function.
Add an inline comment above each step describing why it is necessary,
and a block comment summarizing the algorithm at the top.

Génération de fichiers README​

Demandez à Cursor de générer un README de projet à partir de votre base de code :

Read the package.json, src/index.ts, and the docs/ folder. Generate a
README.md with: project title and description, installation instructions,
usage examples, API reference summary, configuration options, and a
contributing guide. Use badges for CI status and license.

Export Markdown et sites de documentation​

Génération de sortie TypeDoc​

TypeDoc génère du HTML de référence d'API à partir de TypeScript :

npm install -D typedoc
// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api/reference",
  "theme": "default",
  "excludePrivate": true,
  "excludeInternal": true,
  "readme": "none",
  "githubPages": false
}

Exécutez-le :

npx typedoc
astuce

TypeDoc respecte les commentaires TSDoc. Plus vos TSDoc sont riches, plus la référence générée est utile. Ajoutez des blocs @example à chaque fonction publique pour que la documentation inclue du code copiable-collable.

Export vers Markdown​

Pour un site de documentation basé sur Markdown (compatible avec Docusaurus, VitePress ou MkDocs), utilisez typedoc-plugin-markdown :

npm install -D typedoc typedoc-plugin-markdown
// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api/markdown",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none"
}

La sortie est un ensemble de fichiers .md, un par module, que vous pouvez déposer directement dans un site de documentation.

Construction d'un site Docusaurus​

npx create-docusaurus@latest my-docs classic
cd my-docs
npm install --save @docusaurus/preset-classic

Ajoutez le Markdown généré à docs/ et configurez la barre latérale :

// sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'API Reference',
      items: [
        'api/markdown/index',
        'api/markdown/modules/HttpClient',
        'api/markdown/modules/Cart',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      items: ['guides/getting-started', 'guides/configuration'],
    },
  ],
};

Export d'OpenAPI vers Markdown​

Utilisez redoc-cli pour exporter votre spec OpenAPI vers une page HTML autonome :

npx redoc-cli build docs/api/openapi.yaml --output docs/api/index.html

Pour une sortie Markdown, utilisez widdershins :

npm install -g widdershins
widdershins docs/api/openapi.yaml -o docs/api/markdown/api.md
attention

La sortie de Widdershins est verbeuse. Revoyez et élaguez le Markdown généré, en particulier les exemples et les tableaux de schéma, pour garder vos docs lisibles. L'IA de Cursor peut résumer la sortie : collez-la et saisissez « condenser cette documentation API en une page de référence concise. »

Bonnes pratiques de documentation dans Cursor​

Garder les commentaires près du code​

La documentation qui vit loin du code devient obsolète. Préférez le TSDoc en ligne aux pages Wiki séparées pour la référence d'API. Utilisez le Markdown externe uniquement pour les guides et tutoriels qui couvrent plusieurs modules.

Documenter l'intention, pas l'implémentation​

// BAD — restates the code
/** Sets i to i + 1 */
function increment(i: number): number {
  return i + 1;
}

// GOOD — explains why
/**
 * Increments a counter, wrapping at MAX_SAFE_INTEGER to prevent overflow.
 * Used by the rate limiter to count requests per window.
 */
function increment(i: number): number {
  return i === Number.MAX_SAFE_INTEGER ? 0 : i + 1;
}

Utiliser les exemples abondamment​

Chaque fonction publique devrait avoir au moins un bloc @example. Les exemples servent doublement de tests exécutables quand vous utilisez des outils comme doctest ou doctest-ts.

Maintenir le changelog à jour​

Maintenez un CHANGELOG.md suivant les conventions Keep a Changelog. L'IA de Cursor peut générer des entrées à partir des messages de commit :

Read the git log since the last release tag and generate a CHANGELOG.md
entry following the Keep a Changelog format. Group changes into Added,
Changed, Fixed, and Removed sections.
astuce

Forcez les mises à jour du changelog en CI avec un outil comme changesets ou danger.js. Un build qui échoue lorsqu'une entrée de changelog manque maintient la documentation honnête.

Valider les liens​

Les liens cassés érodent la confiance dans la documentation. Utilisez un vérificateur de liens en CI :

npx markdown-link-check docs/**/*.md

Pièges courants et comment les éviter​

Documentation obsolète​

Le problème de documentation le plus courant est la dérive entre le code et la documentation. Atténuez par :

  • Génération de la référence d'API à partir du code (TypeDoc, OpenAPI).
  • Exécution de tests de contrat en CI.
  • Revue de la documentation dans le cadre de la checklist de pull request.
attention

Ne désactivez jamais un linter ou un test de contrat qui échoue avec un commentaire « corriger la doc plus tard. » La documentation obsolète est pire qu'absente car elle induit activement les lecteurs en erreur.

Sur-documentation du code trivial​

Toutes les lignes n'ont pas besoin de commentaire. Documentez :

  • Les API publiques et fonctions exportées.
  • Les algorithmes et règles métier non évidents.
  • Les contournements et limitations connus.

Sautez les commentaires pour les getters, setters et one-liners évidents.

Formatage incohérent​

Un formatage TSDoc incohérent donne un aspect non professionnel à la documentation. Épinglez un formateur :

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[markdown]": {
    "editor.wordWrap": "on"
  }
}

Ignorer l'audience​

Écrivez la documentation pour le lecteur, pas l'auteur. Un consommateur d'API n'a pas besoin de connaître les structures de données internes — il a besoin d'exemples de requête/réponse, de détails d'authentification et de conseils de gestion d'erreurs. Adaptez chaque document à son public cible.

astuce

Lors de la génération de docs avec l'IA de Cursor, spécifiez l'audience dans le prompt : « Générer une documentation API destinée aux développeurs frontend intégrant ce service pour la première fois. » L'IA ajuste le ton, le niveau de détail et la complexité des exemples en conséquence.

Résumé​

Cursor est un environnement puissant pour générer et maintenir la documentation de code. JSDoc et TSDoc fournissent une documentation en ligne, sensible à l'IntelliSense pour JavaScript et TypeScript. Les spécifications OpenAPI/Swagger décrivent les API REST de manière exhaustive et permettent des aperçus interactifs, la génération de clients et les tests de contrat. L'assistant IA de Cursor accélère chaque étape — génération de commentaires à partir du code, scaffolding de specs OpenAPI et export de livrables Markdown. Commencez par installer les extensions de documentation, documentez vos API publiques avec TSDoc, scaffoldez une spec OpenAPI pour vos endpoints REST, et laissez l'IA de Cursor gérer la rédaction répétitive pendant que vous vous concentrez sur la clarté, la précision et l'expérience de vos lecteurs.