概要

関数（変数の場合もあります）の宣言の直前に書かれているこのコメントは Javadoc や JSDoc, phpDocumentor などと呼ばれるものです。これは通常ソースコードの中に書くコメントとは違い、あとでツールにコードを読ませて「コードの中にある関数がどういった処理をしているのか、その関数はどうやって使うのか」の一覧を出力（ブラウザで見ることのできる html 形式やリッチテキストフォーマットの rtf 形式で出力されることが多いようです）させるために使います。

VS Code など高機能なエディタですと、編集中のソースコードに書かれているこれらのコメントを自動で認識し、その関数を使うとき入力支援などのコード補完機能が働くようになっています。

実際の記述方法

書き方としては /** で始まり */ で終わります。記述内容としては

• この関数（もしくは変数）が何のために宣言されてどういう目的で使うものなのかの説明
• 引数（@param）
• 返り値（@return もしくは @returns）

の3つが最低限の構成要素といえます。

@return と @returns は得られる結果は同じなのでどちらでも大丈夫です。コーディング規約などで定められている場合は指定されているもので記述してください。

ほかの構成要素としては

• @author
  この関数のコードを書いた人の名前です。責任の範囲を明確にできます
• @see
  関数を利用するときに併せて見ておいてほしいオブジェクトや資料を記述します

などがありますが、言語によって差異があるので各々で開発言語に合わせて調べて使いましょう。

サンプル

例えば「日付型データを受け取り和暦年月日の文字列にして返却する」という関数であれば

/**
* 受け取った Date 型データを和暦の年月日の文字列型にして返却
*
* @author Xiaokunlun
* @param {date} 和暦に変換したい日付型データ
* @returns {string} 和暦の年月日の文字列
* @example
* dateToWarekiString(new Date(2024, 4, 1)); //returns "令和6年4月1日"
*/

のように記述する形になります。