読者です 読者をやめる 読者になる 読者になる

すたらブログ

文系Webプログラマの備忘録

JavaScript: JSDoc3に即時関数内の記述も拾ってもらうための苦肉の策

JavaScript

JSDocのバージョン

JSDoc 3.3.0-dev

結論

@globalをつけることにしました。

経緯

以前作ったjQueryプラグインのコメントをJSDocに対応させてドキュメントを出力させてみたら、なぜかほとんどが抜け落ちています。
調べてみたところ、どうやら即時関数の中のコメントはJSDocが拾ってくれないそうです。

名前空間の場合は、下記のような方法で対処できるようです。

しかし、今回のjQueryプラグインのような、グローバルスコープのどれにも属さない、クロージャの中のクラスをドキュメントにするにはどうすればいいのか…。
しかたなく、結論にもある通り@globalを使うことにしました。

jQuery
(function($) {
    /**
    * @global
    * @memberof jQuery
    */
    $.fn.addInputArea = function(option) {
        return this.each(function() {
            new AddInputArea(this, option);
        });
    };

    /**
    * @global
    * @constructor
    */
    function AddInputArea(elem, option) {
        // 省略
    }

    $.extend(AddInputArea.prototype, /** @lends AddInputArea.prototype */ {
        // 省略
    });
})( /** namespace */ jQuery);

これできちんとドキュメントが作成されました。
『グローバルスコープにはないのに偽って@globalを使うのは用法として間違っているのでは…』と思いましたが、上の公式ドキュメントをよく読んでみると、この@globalはもともとこういう場面で使うタグのようですね。