Best way to document anonymous objects and functions with jsdoc

Question

Edit: This is technically a 2-part question. I chose the best answer that covers the question as a whole and is related to the answer that handles the specific question.

What is the best way to document anonymous objects and functions with jsdoc?

/** * @class {Page} Page Class specification */ var Page = function() { /** * Get a page from the server * @param {PageRequest} pageRequest Info on the page you want to request * @param {function} callback Function executed when page is retrieved */ this.getPage = function(pageRequest, callback) { }; }; 

There is no PageRequest or callback object in the code. They will be provided by getPage() at runtime. But I would like to be able to determine what an object and function are.

I can get away with creating a PageRequest object to document that:

 /** * @namespace {PageRequest} Object specification * @property {String} pageId ID of the page you want. * @property {String} pageName Name of the page you want. */ var PageRequest = { pageId : null, pageName : null }; 

And that’s fine (although I am open to better ways to do this).

What is the best way to document a callback function? I want to inform in the document that, for example, the callback function looks like:

 callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus) 

Any ideas how to do this?

Answer 1

You can document material that does not exist in the code using the @name tag:

  /** Description of the function @name IDontReallyExist @function @param {String} someParameter Description */ /** The CallAgain method calls the provided function twice @param {IDontReallyExist} func The function to call twice */ exports.CallAgain = function(func) { func(); func(); } 

Here is the @ tag name documentation . You can also find name paths .

Answer 2

You can use @callback or @typedef .

 /** * @callback arrayCallback * @param {object} element - Value of array element * @param {number} index - Index of array element * @param {Array} array - Array itself */ /** * @param {arrayCallback} callback - function applied against elements * @return {Array} with elements transformed by callback */ Array.prototype.map = function(callback) { ... } 

Answer 3

To compliment studgeek's answer, I gave an example that shows what JsDoc with the Google Closure Compiler allows you to do.

Note that documented anonymous types are removed from the generated mini file, and the compiler ensures that the actual objects are passed (when possible). However, even if you are not using the compiler, it can help the next developer and tools like WebStorm (IntelliJ) to figure this out and give you code completion.

 // This defines an named type that you don't need much besides its name in the code // Look at the definition of Page#getPage which illustrates defining a type inline /** @typedef { pageId : string, pageName : string, contents: string} */ var PageResponse; /** * @class {Page} Page Class specification */ var Page = function() { /** * Get a page from the server * @param {PageRequest} pageRequest Info on the page you want to request * * The type for the second parameter for the function below is defined inline * * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback * Function executed when page is retrieved */ this.getPage = function(pageRequest, callback) { }; }; 

Answer 4

@link can add inline links to methods and classes.

 /** * Get a page from the server * @param {PageRequest} pageRequest Info on the page you want to request * @param {function} callback Function executed when page is retrieved<br /> * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus) */ this.getPage = function (pageRequest, callback) { }; 

Not perfect, but he does his job.

Answer 5

In the annotations of the Google Closure Type Compiler compiler, for this there is the ability to specify the type for specific arguments, the type of the return value, and even that. Many libraries are looking for comments on the comments of the Google Closure compiler because they want to use it to compress their code. So he got some momentum. The disadvantage is that I do not see a way to give a description.

To provide a description, the JSDoc Toolkit Parameters with properties option may work (see the bottom of the page). This is what I am doing right now. The JSDoc Toolkit is ready to get started on V3, so feedback can be good.

Answer 6

You can use @see to refer to another method within the same class. This method will never be used; it will just be used for documentation purposes.

 /** * @class {Page} Page Class specification */ var Page = function() { /** * Get a page from the server * @param {PageRequest} pageRequest Info on the page you want to request * @param {function} callback Function executed when page is retrieved * @see #getPageCallback */ this.getPage = function (pageRequest, callback) { }; /** * Called when page request completes * @param {PageResponse} pageResponse The requested page * @param {PageRequestStatus} pageRequestStatus Status of the page */ //#ifdef 0 this.getPageCallback = function (pageResponse, pageRequestStatus) { }; //#endif }; 

If you use some kind of assembly system, the dummy method can be easily excluded from the assembly.