JSDoc

Motivation

Wenn du existierende Funktionen benutzen möchtest, dann wäre es doch praktisch, wenn deine IDE dir direkt mitteilt, was die Funktion bewirkt und welche Typen die Parameter haben. Das lässt sich mit JSDoc erreichen.

Ziele

• Du weisst, wie du in JavaScript zu Klassen und Funktionen eine Beschreibung hinzufügen kannst, die dir deine Entwicklungsumgebung anzeigt, wenn du diese mittels Auto-Completion auswählst.
• Du weisst, wie du in JavaScript eine Typ-Angabe machen kannst (die aber zur Laufzeit nichts bewirkt).

Basics

In TypeScript kannst du jeder Variable einen Typ und jeder Funktion einen Rückgabewert zuweisen. Das geht in JavaScript nicht so einfach.

Trotzdem kannst du dank des JSDoc-Projekts (https://jsdoc.app/about-getting-started.html) Typ-Angaben machen, damit deine Entwicklungsumgebung sich beschwert, wenn beispielsweise in einer Funktion ein Wert eines falschen Types übergeben wird.

In nächsten Beispiel siehst du, wie du in einer Funktion die Typen spezifizieren kannst:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

/**
 * Diese Funktion leitet die Argumente dem Konstruktor der Klasse `Person` weiter.
 * @param {string} name                 Der Name der Person
 * @param {Object} namedArgs            (Eigentlich unnötig, wird aber als Label für die Referenz auf die named Parameter benötigt)
 * @param {number} [namedArgs.age]      Alter
 * @param {string} [namedArgs.gender]   Geschlecht, darf irgend ein String sein.
 * @returns {Person}                    Ein Personen-Objekt mit den übergebenen Werten.
 */
function createPerson(name, { age = undefined, gender = undefined }) {
  return new Person(name, {
    age: age,
    gender: gender,
  });
}

Deine Entwicklungsumgebung kann diese Informationen nun auch anzeigen:

Tags

Im vorherigen JSDoc wurden viele Tags verwendet. Hier eine kleine Übersicht zu den wichtigsten:

• @param: Damit wird ein Parameter beschrieben.
• @returns: Damit wird der Rückgabewert beschrieben.
• {number}: Das ist eine Typangabe. Im Beispiel muss das Argument eine Zahl sein.
• [namedArgs.gender]: Die eckigen Klammern spezifizieren das Argument als optional (nullable). Ansonsten sollten die Argumente nicht den Wert undefined oder null annehmen.

Eine Auflistung aller JSDoc-Tags findest du hier: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

Fehler anzeigen, wenn Typen falsch sind

In VS Code gibt es die Möglichkeit, dass die IDE eine Meldung ausgibt, wenn du Werte des falschen Typs übergibst.

Um hiervon Gebrauch zu machen, kann im Projekt-Verzeichnis eine jsconfig.json-Datei angelegt werden. Folgende Konfiguration könnte für Browser-Anwendungen Sinn ergeben, wenn sich die JS-Dateien beispielsweise im Ordner “${workspaceFolder}/static/js/” befinden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "baseUrl": ".",
    "checkJs": true,
    "importHelpers": true,
    "lib": ["DOM", "ES2021", "DOM.Iterable"]
  },
  "exclude": ["node_modules"],
  "include": ["static/js/*"]
}

Dank dieser Konfiguration würde dir VS Code nun einen Fehler anzeigen, wenn du statt einem string eine number übergeben würdest: