Zum Hauptinhalt springen

Code-Dokumentationserstellung in Cursor: Ein vollständiger Leitfaden

Code-Dokumentation in Cursor

Gute Dokumentation ist die Brücke zwischen Code und den Personen, die ihn verwenden — seien es Mitentwickler, API-Nutzer oder Ihr zukünftiges Ich. Dokumentation umfasst Inline-Kommentare, API-Referenzen, Typ-Annotationen und eigenständige Leitfäden. Cursor ist mit seinem KI-Assistenten und dem reichhaltigen Erweiterungs-Ökosystem eine herausragende Umgebung für die Erstellung und Pflege von Dokumentation. Es kann JSDoc- und TSDoc-Kommentare aus Code generieren, OpenAPI-Spezifikationen erstellen und aus Ihrer bestehenden Codebasis poliertes Markdown exportieren.

Dieser Leitfaden behandelt den kompletten Dokumentations-Workflow in Cursor: das Schreiben von JSDoc und TSDoc, das Generieren von OpenAPI/Swagger-Spezifikationen, den Einsatz von KI zur Dokumentationserstellung und den Export von Markdown-Lieferobjekten. Egal, ob Sie eine Bibliothek, einen internen Dienst oder eine öffentliche API dokumentieren — die folgenden Techniken helfen Ihnen, klare, genaue und wartbare Dokumentation zu erstellen.

Einrichten der Dokumentations-Tools in Cursor​

Wesentliche Erweiterungen​

Installieren Sie diese Erweiterungen, um die Dokumentationsarbeit in Cursor zu verstärken:

  1. Markdown All in One — Tastenkombinationen, Inhaltsverzeichnis-Erstellung und Listenbearbeitung für .md-Dateien.
  2. Markdown Preview Enhanced — Live-Vorschau mit Formeln, Diagrammen und Code-Ausführung.
  3. Docs View — side-by-side Markdown-Vorschau, die sich beim Tippen aktualisiert.
  4. OpenAPI (Swagger) Editor — Schema-Validierung und Vorschau für OpenAPI YAML/JSON.
  5. Prettier — einheitliche Formatierung für Markdown und YAML.
tipp

Die OpenAPI-Erweiterung bietet einen Live-Vorschau-Bereich, der Ihre openapi.yaml in eine interaktive API-Dokumentationsseite umwandelt, ähnlich wie Redoc oder Swagger UI. So können Sie an Ihrer Spezifikation arbeiten und das Ergebnis sofort sehen, ohne Cursor zu verlassen.

Projektstruktur für Dokumentation​

Ein dokumentationsfreundliches Projektlayout:

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

JSDoc: JavaScript-Code dokumentieren​

Grundlegende JSDoc-Syntax​

JSDoc ist der Standard für die Dokumentation von JavaScript-Code. Der KI-Assistent von Cursor generiert JSDoc-Kommentare automatisch aus Funktionssignaturen.

/**
 * 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);
}
tipp

Cursor's IntelliSense liest JSDoc-Kommentare und zeigt sie in Hover-Tooltips, Autovervollständigungsvorschlägen und der Signaturhilfe an. Gut geschriebene JSDoc-Kommentare lassen ein JavaScript-Projekt für Nutzer genauso typsicher wirken wie TypeScript.

Klassen und Module dokumentieren​

/**
 * 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);
  }
}

Benutzerdefinierte Typdefinitionen​

Definieren Sie wiederverwendbare Typen mit @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 };
}
warnung

JSDoc-@typedef-Definitionen müssen vor ihrer Referenzierung erscheinen. Platzieren Sie gemeinsame Typen in einer einzigen types.js-Datei und verwenden Sie @see oder Imports, um sie modulübergreifend zu referenzieren. Eine gemischte Platzierung führt dazu, dass IntelliSense "any" anstelle des korrekten Typs anzeigt.

TSDoc: TypeScript-Code dokumentieren​

TSDoc vs. JSDoc​

TSDoc ist eine Variante von JSDoc, die für TypeScript standardisiert wurde. Sie verwendet dieselbe Kommentar-Syntax, konzentriert sich aber auf die Beschreibung von Typen, die bereits in den TypeScript-Signaturen deklariert sind, und lässt daher redundante @param-Typ-Annotationen weg.

/**
 * 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);
}
tipp

In TypeScript stehen die Parametertypen bereits in der Signatur. Sie in @param als {number} zu wiederholen ist redundant und führt zu Drift. Verwenden Sie den TSDoc-Stil — beschreiben Sie die Bedeutung, nicht den Typ.

Schnittstellen und Typen dokumentieren​

/**
 * 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;
  }
}

Die TSDoc-Erweiterung verwenden​

Installieren Sie die TSDoc-Erweiterung für Snippet-Unterstützung und Validierung. Sie bietet:

  • Snippets für @param, @returns, @throws, @example.
  • Linting für fehlerhafte TSDoc-Tags.
  • Automatische Erstellung von Kommentar-Stubs aus TypeScript-Signaturen.
tipp

Tippen Sie die Zeichen /** über einer Funktionsdeklaration und drücken Sie Enter. Cursor (unterstützt durch den TypeScript-Sprachserver) generiert automatisch einen TSDoc-Stub mit @param- und @returns-Platzhaltern für jeden Parameter.

OpenAPI und Swagger​

Was ist OpenAPI?​

OpenAPI (früher Swagger) ist der branchenweite Standard zur Beschreibung von REST-APIs. Eine einzige openapi.yaml-Datei dokumentiert jeden Endpunkt, Request-Body, Response-Schema und jede Authentifizierungsmethode und ermöglicht die automatische Generierung von Client-SDKs, interaktiver Dokumentation und Contract-Tests.

Eine OpenAPI-Spezifikation schreiben​

# 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.
tipp

Die OpenAPI-Erweiterung in Cursor wandelt dieses YAML in eine interaktive Vorschau um. Klicken Sie auf einen Endpunkt, um seine Parameter und Antworten aufzuklappen, und verwenden Sie die Schaltfläche „Try it out", um direkt aus dem Editor Live-Anfragen zu senden.

OpenAPI aus Code generieren​

Verwenden Sie für Express-Anwendungen swagger-jsdoc, um OpenAPI aus JSDoc-Annotationen zu extrahieren:

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));

Annotieren Sie Ihre Routen:

/**
 * @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);
warnung

Code-first-OpenAPI-Generierung weicht von der tatsächlichen Implementierung ab, wenn Entwickler Routen ändern, ohne die Annotationen zu aktualisieren. Führen Sie einen Contract-Test (mit Dredd oder Schemathesis) in CI aus, um Drift frühzeitig zu erkennen.

OpenAPI-Spezifikationen validieren​

Installieren Sie @redocly/cli für Linting und Bündelung:

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

Fügen Sie einen CI-Schritt hinzu:

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

KI-gestützte Dokumentationserstellung​

JSDoc und TSDoc aus Code generieren​

Der KI-Assistent von Cursor glänzt darin, Dokumentationskommentare aus bestehendem Code zu erstellen. Markieren Sie eine Funktion, drücken Sie Ctrl+K, und geben Sie folgenden Prompt ein:

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

Cursor liest die Signatur und erstellt einen vollständigen Kommentar. Prüfen Sie das Ergebnis auf Richtigkeit und übernehmen Sie es dann.

tipp

Für die Massengenerierung markieren Sie eine gesamte Datei und bitten Sie Cursor, „jeder exportierten Funktion und Klasse TSDoc-Kommentare hinzuzufügen". Die KI verarbeitet jede Deklaration nacheinander und spart Ihnen Minuten manuellen Tippens.

OpenAPI aus Routendateien generieren​

Geben Sie Cursor diesen Prompt bei geöffneter Routendatei:

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.

Die KI analysiert jeden Route-Handler und erstellt ein entsprechendes OpenAPI-Pfadobjekt. Führen Sie das Ergebnis in Ihre Haupt-openapi.yaml zusammen.

Komplexe Logik dokumentieren​

Bei Algorithmen mit nicht offensichtlichem Verhalten bitten Sie Cursor, erklärende Kommentare zu schreiben:

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.

README-Dateien generieren​

Bitten Sie Cursor, eine Projekt-README aus Ihrer Codebasis zu generieren:

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.

Markdown-Export und Dokumentations-Seiten​

TypeDoc-Ausgabe generieren​

TypeDoc generiert API-Referenz-HTML aus 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
}

Führen Sie es aus:

npx typedoc
tipp

TypeDoc respektiert TSDoc-Kommentare. Je reichhaltiger Ihre TSDoc-Kommentare, desto nützlicher die generierte Referenz. Fügen Sie jeder öffentlichen Funktion @example-Blöcke hinzu, damit die Dokumentation kopierbaren Code enthält.

Export nach Markdown​

Verwenden Sie für eine Markdown-basierte Dokumentations-Site (kompatibel mit Docusaurus, VitePress oder MkDocs) 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"
}

Die Ausgabe ist eine Reihe von .md-Dateien, eine pro Modul, die Sie direkt in eine Dokumentations-Site einfügen können.

Eine Docusaurus-Site aufbauen​

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

Fügen Sie das generierte Markdown zu docs/ hinzu und konfigurieren Sie die Sidebar:

// 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'],
    },
  ],
};

OpenAPI nach Markdown exportieren​

Verwenden Sie redoc-cli, um Ihre OpenAPI-Spezifikation in eine eigenständige HTML-Seite zu exportieren:

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

Verwenden Sie für die Markdown-Ausgabe widdershins:

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

Die Ausgabe von Widdershins ist sehr umfangreich. Prüfen und kürzen Sie das generierte Markdown, insbesondere die Beispiele und Schema-Tabellen, um Ihre Dokumentation lesbar zu halten. Die KI in Cursor kann die Ausgabe zusammenfassen: Fügen Sie sie ein und geben Sie den Prompt „Fasse diese API-Dokumentation zu einer prägnanten Referenzseite zusammen."

Best Practices für Dokumentation in Cursor​

Kommentare nah am Code halten​

Dokumentation, die weit vom Code entfernt ist, veraltet schnell. Bevorzugen Sie inline TSDoc gegenüber separaten Wiki-Seiten für API-Referenzen. Verwenden Sie externes Markdown nur für Leitfäden und Tutorials, die mehrere Module umspannen.

Intention dokumentieren, nicht Implementierung​

// 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;
}

Beispiele großzügig verwenden​

Jede öffentliche Funktion sollte mindestens einen @example-Block haben. Beispiele dienen gleichzeitig als ausführbare Tests, wenn Sie Tools wie doctest oder doctest-ts verwenden.

Changelog aktuell halten​

Pflegen Sie eine CHANGELOG.md nach den Keep-a-Changelog-Konventionen. Die KI von Cursor kann Einträge aus Commit-Nachrichten generieren:

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.
tipp

Erzwingen Sie Changelog-Updates in CI mit einem Tool wie changesets oder danger.js. Ein fehlgeschlagener Build, wenn ein Changelog-Eintrag fehlt, hält die Dokumentation ehrlich.

Defekte Links untergraben das Vertrauen in die Dokumentation. Verwenden Sie einen Link-Checker in CI:

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

Häufige Fallstricke und wie man sie vermeidet​

Veraltete Dokumentation​

Das häufigste Dokumentationsproblem ist die Drift zwischen Code und Dokumentation. Mildern Sie dies durch:

  • Generierung der API-Referenz aus Code (TypeDoc, OpenAPI).
  • Ausführung von Contract-Tests in CI.
  • Prüfung der Dokumentation als Teil der Pull-Request-Checkliste.
warnung

Deaktivieren Sie niemals einen fehlschlagenden Linter oder Contract-Test mit einem „Dokumentation später reparieren"-Kommentar. Veraltete Dokumentation ist schlimmer als keine Dokumentation, weil sie Leser aktiv in die Irre führt.

Trivialen Code überdokumentieren​

Nicht jede Zeile braucht einen Kommentar. Dokumentieren Sie:

  • Öffentliche APIs und exportierte Funktionen.
  • Nicht offensichtliche Algorithmen und Geschäftsregeln.
  • Workarounds und bekannte Einschränkungen.

Lassen Sie Kommentare für selbsterklärende Getter, Setter und Einzeiler weg.

Inkonsistente Formatierung​

Inkonsistente TSDoc-Formatierung lässt Dokumentation unprofessionell wirken. Fixieren Sie einen Formatter:

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

Zielgruppe ignorieren​

Schreiben Sie Dokumentation für den Leser, nicht für den Autor. Ein API-Nutzer muss nicht die internen Datenstrukturen kennen — er braucht Request/Response-Beispiele, Authentifizierungsdetails und Hinweise zur Fehlerbehandlung. Passen Sie jedes Dokument an seine Zielgruppe an.

tipp

Geben Sie beim Generieren von Dokumentation mit der KI von Cursor die Zielgruppe im Prompt an: „Generiere API-Dokumentation für Frontend-Entwickler, die diesen Dienst zum ersten Mal integrieren." Die KI passt Ton, Detailgrad und Beispielkomplexität entsprechend an.

Zusammenfassung​

Cursor ist eine leistungsstarke Umgebung für die Erstellung und Pflege von Code-Dokumentation. JSDoc und TSDoc bieten inline-, IntelliSense-fähige Dokumentation für JavaScript und TypeScript. OpenAPI/Swagger-Spezifikationen beschreiben REST-APIs umfassend und ermöglichen interaktive Vorschauen, Client-Generierung und Contract-Tests. Der KI-Assistent von Cursor beschleunigt jeden Schritt — generiert Kommentare aus Code, erstellt OpenAPI-Spezifikationen und exportiert Markdown-Lieferobjekte. Beginnen Sie mit der Installation der Dokumentations-Erweiterungen, dokumentieren Sie Ihre öffentlichen APIs mit TSDoc, erstellen Sie eine OpenAPI-Spezifikation für Ihre REST-Endpunkte, und überlassen Sie der KI von Cursor die wiederkehrende Erstellungsarbeit, während Sie sich auf Klarheit, Genauigkeit und die Erfahrung Ihrer Leser konzentrieren.