CODEWITHSUNDEEP
jsdoc3
user128511
user128511

Reputation:

How to get JSDoc3 to document module functions

Given this file

/*
 * 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,
  };
});

I get no docs from JSDoc. It creates a module-stuffutils.html but the file is bascially empty.

I tried /** @exports getStuff */ above the define, below the define, in the function docs. I tried various forms of @static, @alias, @public. The best I was able to get is for it to show up as a global function which is obviously not what I'm looking for. Ideas?

jsdoc

I tried this which seems to follow the docs

"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;
});

But even that doesn't really work.

jsdocs output 2

Docs are inserted twice. Two functions are documented instead of one. GetStuffCallback is not documented. I can't move the definition of getStuff because other functions use it. In other words if I just made it an anonymous function of the object assigned to exports I wouldn't be able to call it from within this module. Example of what I mean

/**
 * 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;

Hopefully you can see above why the functions can't be anonymous values of the exports object.

Upvotes: 1

Views: 1081

Answers (1)

Wiki
Wiki

Reputation: 351

Try to set one @exports tag and @memberOf in the type definition

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
    };
});

You have to spell out the namespace in the @param field otherwise there won't be a link.

Upvotes: 2

Related Questions