Hinzufügen von Metadaten zu Ihrer Dokumentation
Die Bereitstellung einer guten Dokumentation ist eine wesentliche Aufgabe für jeden Entwickler. Es hilft nicht nur Ihren Kollegen, Ihre Argumentation und vielleicht Ihren Denkprozess schnell zu verstehen, sondern hilft Ihnen auch, schneller in den Code einzusteigen, falls Sie nach ein paar Monaten wieder darauf zurückkommen.
Ich dachte daher daran, eine (unvollständige) Liste von speziellen Tags zu erstellen, die mit JSDoc-Kommentaren verwendet werden können. Das sind die, die ich persönlich am häufigsten verwende und die sich als echter Vorteil erwiesen haben.
Ein einfacher Starter
Das folgende Codebeispiel zeigt ein einfaches, grundlegendes Beispiel, das für jede Dokumentation verwendet werden sollte. Es kommentiert den Zweck, Parameter sowie den Rückgabetyp.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Beispielcode in der Dokumentation
Sie können ein echtes Inline-Codebeispiel mit dem „@example“-Tag bereitstellen, um bestimmte Anwendungsfälle klarer zu machen. Dieses Tag kann auch verwendet werden, um mögliche Grenzfälle in einem realen Szenario schnell aufzuzeigen.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Mitglied in welchem Modul
Verwenden Sie das „@memberOf“-Tag, um zu definieren, welches Modul oder welche übergeordnete Variable den dokumentierten Code hostet.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Link-Anmerkung
Sie können das „@see“-Tag zusammen mit dem „@link“-Tag verwenden, um eine korrekt formatierte URL-Dokumentation bereitzustellen, anstatt einige URLs in die Hauptdokumentation einzufügen.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Generische Typdokumentation
Wenn Ihr Code generische Typen verwendet, können Sie den „@template“-Tag verwenden, um den generischen Typnamen zu definieren. Dieser Name wird dann in den gemeinsamen „@param“-Tags als Typreferenz verwendet.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Definieren des Autors eines Codestücks
In bestimmten Fällen ist es wichtig, auch den Autor zu kommentieren. Dies kann einfach mit dem „@author“-Tag erreicht werden. Sie können nicht nur Ihren Namen, sondern auch eine E-Mail als Kontaktreferenz angeben.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Veralteter Code
Zum „@deprecated“-Tag gibt es nicht viel zu sagen, da es genau das tut, was man erwarten würde. Dieses Tag wird häufig in APIs verwendet und kann auch auf den neuen Code verweisen.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Ausführung
Verwenden Sie das „@version“-Tag, um eine Version für den angegebenen Code zu dokumentieren. Beachten Sie, dass dieses Tag nicht auf die Anwendungsversion verweist, sondern wirklich auf seine eigene. Ein Inkrement dieser Version bedeutet, dass sich dieser spezifische Code geändert hat.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Seit wann ist der Code verfügbar
Mit dem „@since“-Tag können Sie dokumentieren, ab welcher Versionsnummer der öffentliche API der folgende Code hinzugefügt wurde. Wichtig hierbei ist, dass die Version jetzt auf den Anwendungsbereich verweist. Dies steht im Gegensatz zum „@version“-Tag von zuvor, das auf den spezifischen Codeblock beschränkt ist, den es dokumentiert.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
