Aufgabe 16 - Dokumentiere deine Bibliothek

Worum geht es?

Sie dokumentieren bestehenden Code mit JSDoc so gut, dass andere ihn benutzen können, ohne hineinzusehen (siehe Kapitel API-Dokumentation erstellen).

In dieser Übung üben Sie:

Dokumentieren: @param, @returns und Beschreibungen auf Methodenebene.
Perspektive wechseln: Doku aus Nutzersicht schreiben.
Bewerten: gute von schlechter Doku unterscheiden.

Benötigte Unterlagen

VS Code (Hover-Vorschau der JSDoc-Kommentare!),
Ihre Konto-Klasse aus Aufgabe 13 und Ihre Umrechnungs-Funktionen aus der 1. Klasse (Aufgabe 13 des Vorjahres), alternativ die bereitgestellten Vorlagen.

Arbeitsaufträge

Teil A - Funktionen dokumentieren

Versehen Sie fünf Funktionen mit vollständigem JSDoc: Kurzbeschreibung (was, nicht wie!), @param mit Typ und Bedeutung, @returns.
Kontrollieren Sie im Editor: Beim Tippen eines Aufrufs muss Ihre Doku als Tooltip erscheinen.

Teil B - Eine Klasse dokumentieren

Dokumentieren Sie die Klasse Konto: Klassenbeschreibung sowie jede öffentliche Methode und den Getter.
Dokumentieren Sie auch das Verhalten im Fehlerfall (Was passiert bei negativem Betrag? Bei ungedeckter Abhebung?). Genau diese Angaben braucht ein Nutzer.
Private Methoden: kurzer Kommentar genügt. Begründen Sie in einem Satz, warum ausführliche Doku hier weniger wichtig ist.

Teil C - Doku-Review

Tauschen Sie mit einer Kollegin/einem Kollegen nur die Doku (Signaturen + JSDoc, Implementierung abgedeckt/entfernt). Schreiben Sie zu zwei Methoden des anderen einen korrekten Beispielaufruf samt erwartetem Ergebnis, nur aus der Doku heraus. Notieren Sie, wo die Doku nicht ausgereicht hat.

Abgabe

Dokumentierte Dateien plus das schriftliche Ergebnis des Doku-Reviews (was fehlte, was war gut).