NeovimでJSDocを使う
JSやGASでコードを書いていく時に、コメントはどのように書いているだろうか。
手軽に分かりやすく、コードを共有した人が確認しやすいものはないかと調べた結果、JSDocというものを知った。
jsdoc.vimを参考にインストールを行った。
環境
インストールの仕方と使い方
~/.config/nvim/init.vim
" jsdoc
Plug 'heavenshell/vim-jsdoc'
nnoremap j :JsDoc <Enter>
上記を~/.config/nvim/init.vimに記入した。
nnoremap j :JsDoc
の部分は、マッピングをさせている。
通常は:JsDoc+<Enter>で実行されるので、これをjに置き換えた。
これでビジュアルモード時にobjectやfunction上でjを押すだけでJSDocが作成される。
以下はJSDocに関しての簡単なまとめである。詳しくは参考文献のリンクを参照にしてほしい。
コメントの構文に関して
コメントは適切であるかを確かめる必要がある。
/**
* JSDocコメントはスラッシュと2つのアスタリスクから始めます。
* インラインタグは {@code this} のように波括弧で囲みます。
* @desc ブロックタグは必ず行の先頭から開始します。
*/
JSDocのインデント
ブロックタグ内での改行が必要な場合はスペース４つ分のインデントが必要。
/**
* 長いparam/returnアノテーションの説明文の折り返し方を示します。
* @param {string} foo これは1行でおさめるには長すぎるパラメータの
* 説明文です。
* @return {number} この戻り値の説明文は長すぎて、とても1行の中には
* 入りきりません。
*/
project.MyClass.prototype.method = function(foo) {
return 5;
};
ファイルへのコメント
@authorで作成者に関する情報を添付する。
/**
* @fileoverview ファイルの説明を行う。
* 依存関係についての情報
* @author aaa@bbb.com
*/
classへのコメント
/**
* Humanクラス
* @param {number} height ヒトの身長
* @param {number} weight ヒトの体重
* @constructor
*/
class Human{
constructor(height, weight){
this.height = height;
this.weight = weight;
}
}
メソッド・関数へのコメント
/**
* 日付を処理し、休みの日かどうかでtrueかfaleを返します。
* @param {date} date 日付
* @return {boolean}
*/
function isSunday(date){
//...
}