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

すたらブログ

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

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

最終更新:

目次


結論 (追記:2017年4月19日)

苦肉の策でも何でもなく、@externalできれいに表現できます。

/**
 * @file jQuery Plugin: jquery.my-plugin
 * @version 0.0.0
 */
/** @external "jQuery.fn" */
/** @external jQuery */
;(function($) {
  /**
   * @function external:"jQuery.fn".myPlugin
   * @param {object} option
   * @return {object} jQuery object
   */
  $.fn.myPlugin = function(option) {
    return this.each(function() {
      new $.myPlugin(this, option);
    });
  };

  /**
   * @constructor external:jQuery.myPlugin
   * @param {object} elem
   * @param {object} option
   */
  $.myPlugin = function(elem, option) {};

  $.extend($.myPlugin.prototype, /** @lends external:jQuery.myPlugin.prototype */ {
    /** @public */
    method1: function() {},
    /** @public */
    method2: function() {}
  });
})(jQuery);

生成されるドキュメントでは、$.fn.myPluginjQuery.fnのメソッドであると正しく認識されています。
f:id:sutara_lumpur:20170419010109p:plain

プラグイン本体のクラスである$.myPluginも、きちんとjQueryに属しています。
@lendsによってメソッドとも正しくつながっています。
f:id:sutara_lumpur:20170419010358p:plain


以前の内容

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はもともとこういう場面で使うタグのようですね。