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

最終更新: 2017年4月19日

結論 (追記:2017年4月19日)
例
以前の内容

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

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

参照: Use JSDoc: @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.myPluginはjQuery.fnのメソッドであると正しく認識されています。
f:id:sutara_lumpur:20170419010109p:plain

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

以前の内容

JSDocのバージョン

JSDoc 3.3.0-dev

結論

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

参照: Use JSDoc: @global

経緯

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

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

参照: 【訂正エントリ】jsdoc3の使い方が間違ってると指摘を受けたので再評価した - terurouメモ

しかし、今回の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);