ドキュメントへのメタデータの追加
優れたドキュメントを提供することは、すべての開発者にとって不可欠なタスクです。それはあなたの仲間があなたの推論と多分思考プロセスを素早く理解するのを助けるだけでなく、あなたが数ヶ月後にコードに戻った場合にあなたがより速くコードに入るのを助けます。
したがって、JSDocコメントで使用する特別なタグの（不完全な）リストを作成することを考えました。これらは私が個人的に最も頻繁に使用するものであり、真の利益をもたらすことが証明されています。
基本的なスターター
次のコード例は、すべてのドキュメントに使用する必要がある単純で基本的な例を示しています。目的、パラメーター、および戻りタイプに注釈を付けます。
/**
* 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);
}
ドキュメントのサンプルコード
特定のユースケースを明確にするために、「@example」タグを使用して実際のインラインコード例を提供できます。このタグを使用して、実際のシナリオで考えられるエッジケースをすばやく表示することもできます。
/**
* 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);
}
どのモジュールのメンバー
「@memberOf」タグを使用して、文書化されたコードをホストするモジュールまたは親変数を定義します。
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
リンク注釈
メインドキュメントのインラインにいくつかのURLを貼り付ける代わりに、「@ see」タグを「@link」タグと一緒に使用して、正しくフォーマットされたURLドキュメントを提供できます。
/**
* @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);
}
ジェネリック型のドキュメント
コードでジェネリック型を使用している場合は、「@ template」タグを使用して、ジェネリック型の名前を定義できます。この名前は、一般的な「@param」タグで型参照として使用されます。
/**
* @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);
}
コードの作成者を定義する
場合によっては、作成者にも注釈を付けることが重要です。これは、「@author」タグを使用して簡単に実行できます。あなたはあなたの名前だけでなく、連絡先の参照として電子メールを提供することもできます。
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
非推奨のコード
「@deprecated」タグについては、期待どおりの動作をするため、あまり説明する必要はありません。このタグはAPIで一般的に使用され、新しいコードを参照することもできます。
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
バージョン
「@version」タグを使用して、指定されたコードのバージョンを文書化します。このタグはアプリケーションのバージョンを参照していませんが、実際には独自のバージョンを参照していることに注意してください。このバージョンの増分は、この特定のコードが変更されたことを意味します。
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
コードが使用可能になったときから
「@since」タグを使用して、次のコードがパブリックAPIに追加されたバージョン番号を文書化できます。ここで重要なのは、バージョンがアプリケーションスコープを参照するようになったことです。これは、以前の「@version」タグとは対照的です。これは、ドキュメント化された特定のコードブロックにスコープされています。
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
