プログラムを読みやすくするJSDocのコメントを覚える

プログラムを読みやすいものにするためJSDocのコメントを覚えます。

JSDocとは

定義された形式でコメントを書くすることでAPIをドキュメント化してくれます。今回はJSDocのコメントの書き方を覚えます。アノテーション（注釈）とも書かれています。

JSDocのコメントの書き方

JSDocのコメントは/**から始まり*/で終わります。

JSDocのシンプルな書き方

/** これはfooの説明です */
function foo() { 　// do someting... }

 

上記は説明だけのとてもシンプルな書き方です。

JSDocのタグを使った書き方

JSDocにはタグがありコメント内で使用できます。タグは@から始まります。例えばコンストラクタを表す@constructorや引数の@param、返す値を表す@returnなどがあります。たくさんあるので今回は一部のみ使用します。

/**
 * 本を表します
 * @constructor
 */
function Book() { // do someting... }

 

上記はコンストラクターであることを表しています。タグは原則1行に1つです。

/**
 * 本を表します
 *
 * @constructor
 * @param {string} title - 本のタイトル
 * @param {string} author - 本の著者 
 */
function Book(title, author) { // do someting... }

 

上記は引数の説明も追加しています。@paramは型と引数の名前、説明を記述します。

/**
 * ほげを返します
 * @return {string} 
 */
function getHoge() { return 'hoge'; }

 

上記は返却する値の説明を@returnを使って書いています。

JSDocのコメントでプログラムが読みやすくなる

プログラムを書く量は増えますし無くても動くが、可読性は間違いなくあがります。javascriptだけでなく他の言語でも同様の定義があるので使えるようにする。

参考サイト

• use JSDoc
• アノテーションの書き方 – JsDoc3-manual-jp