如何让JSDoc3记录模块功能

Question

鉴于此文件

/*
 * comments
 */

"use strict";

/** @module stuffutils */
define(function() {
  /**
   * @callback GetStuffCallback
   * @param {String[]} array of stuff
   *        Will be empty if no stuff.
   */

  /**
   * Gets the stuff.
   * @param {GetStuffCallback} callback function to call with
   *        stuff.
   */
  var getStuff = function(callback) {
     foobar(callback);
  };

  return {
    getStuff: getStuff,
  };
});

我没有从JSDoc获得文档。它会创建一个module-stuffutils.html，但该文件基本上是空的。

我在函数文档中的define下面的define上面尝试了/** @exports getStuff */。我尝试了各种形式的@static，@alias，@public。我能得到的最好的就是它显示为一个全局功能，这显然不是我想要的。想法？

我试过这个似乎遵循文档

"use strict";

/** @module stuffutils */
define(
  /** @exports stuffutils */
  function() {

  /**
   * @callback GetStuffCallback
   * @param {String[]} array of stuff
   *        Will be empty if no stuff.
   */

  /**
   * Gets the stuff.
   * @param {GetStuffCallback} callback function to call with
   *        stuff.
   *
   */
  var getStuff = function(callback) {
    foobar(callback);
  };


  var exports = {
    /** @function */
    getStuff: getStuff,
  };

  return exports;
});

但即使这样也不行。

文档会被插入两次。记录两个函数而不是一个。 GetStuffCallback未记录在案。我无法移动getStuff的定义，因为其他函数使用它。换句话说，如果我只是将它作为分配给exports的对象的匿名函数，我将无法从该模块中调用它。我的意思是

/**
 * parse url query key=values into an object
 * @param {string} url string with query eg `http://foo.com/?a=1&b=2
 * @returns {object} object of key values. eq `{a:"1",b:"2"}`
 */
var parseQueryString = function(url) {
  ...
}

/**
 * parse current url into object with key/values.
 * (eg. if the current URL is `http://foo.com/?a=1&b=2` this function
 * will return {a:"1",b:"2"})
 * @returns {object} object of key values. eq `{a:"1",b:"2"}`
 */
var parseCurrentLocationQuery = function() {
  return parseQueryString(window.href.location);
};

var exports = {
  parseQueryString: parseQueryString,
  parseCurrentLocationQuery: parseCurrentLocationQuery,
};

return exports;

希望你能看到上面为什么这些函数不能成为exports对象的匿名值。

Answer 1

尝试在类型定义

中设置一个@exports代码和@memberOf

define(/** @exports stuffutils */
    function() {
    /**
     * @callback GetStuffCallback
     * @memberOf module:stuffutils
     * @param {String[]} array of stuff
     *        Will be empty if no stuff.
     */

    /**
     * Gets the stuff.
     * @param {module:stuffutils.GetStuffCallback} callback function to call with
     *        stuff.
     */
    var getStuff = function(callback) {
        foobar(callback);
    };

    return {
        getStuff: getStuff
    };
});

你必须在@param字段中拼出命名空间，否则就不会有链接。