TypeScriptでJSDoc（実際はYUIDoc）のドキュメント生成を試してたら、ちょっと面白い現象が起こったので記事にしてみました。
メソッドのオーバーロードの書き方
TypeScriptにおけるメソッドのオーバーロードの書き方は以下の通りですが、
HogeClass.ts
// オーバーロード定義
public prop(key:string, value:string):void;
public prop(object:Object):void;
// メソッド本体
public prop(key:string, value?:string):void {
...
}
これにJSDocコメントを追加してみます。
JSファイルにコンパイル
最初は以下の感じで書いてみたんですが、
HogeClass.ts
/**
* ここにJSDocコメント
*/
public prop(key:string, value:string):void;
public prop(object:Object):void;
public prop(key:string, value?:string):void {
...
}
これをJSファイルにコンパイルすると、
HogeClass.js
// JSDocコメントが無い！
HogeClass.prototype.prop= function (key, value) {
...
}
JSDocコメントがすっぽり抜けちゃいます。
メソッドのオーバロード定義はコンパイルするとJSファイルからは取り除かれるので、どうやら直前に書いていたコメントも一緒に消えてしまうみたいです。
代わりにメソッド本体の直前にJSDocコメントを書いてから
HogeClass.ts
public prop(key:string, value:string):void;
public prop(object:Object):void;
/**
* ここにJSDocコメント
*/
public prop(key:string, value?:string):void {
...
}
コンパイルしてみます。
HogeClass.js
/**
* ここにJSDocコメント
*/
HogeClass.prototype.prop= function (key, value) {
...
}
今度は上手くいきました。
d.tsファイルを生成
さて、このままd.tsファイルも作ってみましたが、
HogeClass.d.ts
// ここにJSDocコメントが無い！
public prop(key:string, value:string):void;
public prop(object:Object):void;
またJSDocコメントがすっぽり抜けちゃいます。
今度はメソッド本体の方が取り除かれるので、その直前に書いたコメントも一緒に削除されてしまうようです。
また最初に戻って、オーバーロード定義の直前にJSDocコメントを書いてから、
HogeClass.ts
/**
* ここにJSDocコメント
*/
public prop(key:string, value:string):void;
public prop(object:Object):void;
public prop(key:string, value?:string):void {
...
}
d.tsファイルを生成すると、
HogeClass.d.ts
/**
* ここにJSDocコメント
*/
public prop(key:string, value:string):void;
public prop(object:Object):void;
今度は上手くいきました。
完全に間逆ですね。
正解
てことで、JSファイルとd.tsファイルの両方にJSDocコメントを残すやり方は、
HogeClass.ts
/**
* ここにJSDocコメント
*/
public prop(key:string, value:string):void;
public prop(object:Object):void;
/**
* ここにJSDocコメント
*/
public prop(key:string, value?:string):void {
...
}
オーバーロード定義とメソッド本体の両方に書くでした。
HogeClass.js
/**
* ここにJSDocコメント
*/
HogeClass.prototype.prop= function (key, value) {
...
}
HogeClass.d.ts
/**
* ここにJSDocコメント
*/
public prop(key:string, value:string):void;
public prop(object:Object):void;
なにこれ、面倒。。。