How To Document Namespace That Is Also a Function

[michaeldrotar]

I came across an old issue that was similar to mine but seemed to have gotten derailed and closed for not having enough info.. so to hopefully provide better information with a real world scenario (comments shortened for brevity)..

/**
  My lib, which does many different things.
  @namespace
*/
var lib = {};

/**
  Provides ajax functionality

  @alias lib.http
  @namespace
*/
lib.http = lib.namespace('http'); // Create the http namespace to hold my http functions

/**
  Performs a highly configurable http request.
  @alias lib.http
  @method
*/
lib.http = lib.namespace('http', wrap($.http)); // Wrap jQuery's http method inside of a
// Promise and have the method throw actual errors.. by the definition of my namespace function,
// this wrapped function takes the place of the object that previously defined the namespace
// since functions can still have properties and methods.. any children of the previous object
// get attached to this function instead

/**
  Performs a GET request
  @alias get
  @memberOf lib.http
*/
lib.http.get = wrap($.get); // Wrap jQuery's get method inside of a Promise, etc..

/**
  Performs a POST request
  @alias post
  @memberOf lib.http
*/
lib.http.post = wrap($.post); // Wrap jQuery's post method inside of a Promise, etc...

I realize that using a function as a namespace seems odd... I don't often do it.. but there's an elegance in this scenario that I like.

If I want to make an ajax request, I simply do..

lib.http('myUrl', { /* settings */ }).then(function(response) {
});

If I want the convenient shorthand, it's namespaced nicely for me...

lib.http.get('myUrl').then(function(response) {
});

Any alteration of the doc comments that I try.. either lib.http is a function and the get and post functions are not present.. or lib.http is a namespace and it's params and returns are not present.

It would be ideal to have everything on its own namespace page (shortened for brevity):

lib. http
Provides ajax functionality
Source: lib.http.js, line 5

(static) lib.http(url, settings) -> Promise
Performs a highly configurable http request.
Parameters:
Source lib.http.js, line 50
Throws:
Returns:

Methods

(static) get(url, settings) -> Promise
Performs a GET request
...

(static) post(url, settings) -> Promise
Performs a POST request
...

If not possible, having functions as children of functions would at least provide the documentation appropriately..

lib
My lib, which does many different things
Source: lib.http.js, line 5

Namespaces
one
two

Methods

(static) http(url, settings) -> Promise
Performs a highly configurable http request.
Parameters:
Source lib.http.js, line 50
Throws:
Returns:

(static) http.get(url, settings) -> Promise
Performs a GET request
...

(static) http.post(url, settings) -> Promise
Performs a POST request
...

Thanks for your time!

[hegemonic]

You're right, there's not a clean way to document this pattern right now. I agree that this is needed.

[nwoltman]

I've had success with this by using the @variation tag. For instance, all you'd have to do is add @variation 1 to the lib.http method, to have it documented as a separate member of the lib namespace and have get and post documented as part of the lib.http namespace.
When doing this, you just have to remember to write lib.http(1) if you want to reference the lib.http method instead of the namespace.

[hegemonic]

Fixed on master. The fix will be included in JSDoc 3.5.0.

For the following example, the default template now displays the function signature, parameters, and return types for the lib.http method/namespace:

/**
 * My lib, which does many different things.
 * @namespace
 */
var lib = {};

/**
 * Provides ajax functionality
 * @namespace
 * @param {string} foo - the foo
 * @return {number} some number
 */
lib.http = function(foo) {};

/**
 * Performs a GET request
 * @function
 */
lib.http.get = wrap($.get);

/**
 * Performs a POST request
 * @function
 */
lib.http.post = wrap($.post);

This was purely a change to the default template. Third-party templates will need to be updated to support this feature.

One important caveat: This feature won't work correctly unless the function you're using as a namespace is actually represented as a function in your code. That's because the template actually looks at your code to figure out that the namespace is also a function. This is necessary because of a fundamental limitation in JSDoc that can't easily be changed. You can deal with this limitation by doing something like this in your code:

/**
 * My lib, which does many different things.
 * @namespace
 */
var lib = {};

// assign a dummy function for JSDoc
/**
 * Provides ajax functionality
 * @namespace
 * @param {string} foo - the foo
 * @return {number} some number
 */
lib.http = function(foo) {};
// now assign the actual value
lib.http = lib.namespace('http');