How can I tell JSDoc about the structure of an object that is returned. I have found the `@return {{field1: type, field2: type, ...}} description` syntax and tried it:

    /**
     * Returns a coordinate from a given mouse or touch event
     * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
     *         A valid mouse or touch event or a jQuery event wrapping such an
     *         event. 
     * @param  {string} [type=&quot;page&quot;]
     *         A string representing the type of location that should be
     *         returned. Can be either &quot;page&quot;, &quot;client&quot; or &quot;screen&quot;.
     * @return {{x: Number, y: Number}} 
     *         The location of the event
     */
    var getEventLocation = function(e, type) {
        ...
        
        return {x: xLocation, y: yLocation};
    }

While this parses successfully, the resulting documentation simply states:

    Returns: 
        The location of an event
        Type: Object

I am developing an API and need people to know about the object that they will get returned. Is this possible in JSDoc? I am using JSDoc3.3.0-beta1.

JSDoc: Return object structure

In JSDoc, the best documentation I can find shows to use the following if you have an array of a specific type (such as an array of strings) as:

    /**
     * @param {Array.&lt;string&gt;} myStrings All my awesome strings
     */
     function blah(myStrings){
         //stuff here...
     }

How would you replace the below question marks specify an array of objects?


    /**
     * @param {???????} myObjects All of my equally awesome objects
     */
     function blah(myObjects){
         //stuff here...
     }

How to specify an array of objects as a parameter or return value in JSDoc?

According to the JSDoc wiki for [@param](http://code.google.com/p/jsdoc-toolkit/wiki/TagParam) you can indicate a @param is optional using  
&lt;pre&gt;&lt;code&gt;/**
    @param {String} [name]
*/
function getPerson(name) {
}
&lt;/code&gt;&lt;/pre&gt;  
and you can indicate a param [inline](http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs) using
&lt;pre&gt;&lt;code&gt;function getPerson(/**String*/ name) {
}
&lt;/code&gt;&lt;/pre&gt;
And I can combine them like the following, which works ok.
&lt;pre&gt;&lt;code&gt;/**
    @param [name]
*/
function getPerson(/**String*/name) {
}
&lt;/code&gt;&lt;/pre&gt;

But I would like to know if there is a way to do it all inline if possible.

How to indicate param is optional using inline JSDoc?

I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something else?

    Shape.prototype.create = function (shapeType) {
        // shapeType can be &quot;rect&quot;, &quot;circle&quot; or &quot;ellipse&quot;...
        this.type = shapeType;
    };

    Shape.prototype.getType = function (shapeType) {
        // shapeType can be &quot;rect&quot;, &quot;circle&quot; or &quot;ellipse&quot;...
        return this.type;
    };

The second part of the problem is that the possible values of `shapeType` is not known in the file that defines `shapeType` as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values of `shapeType`.

PS: Am using `jsdoc3`

How to document a string type in jsdoc with limited possible values

Previously I&#39;ve always documented my object parameters as follows:

    /**
     * Description of the function
     *
     * @param {Object} config - The configuration
     * @param {String} config.foo
     * @param {Boolean} [config.bar] - Optional value
     * @return {String}
     */
    function doSomething (config = {}) {
      const { foo, bar } = config;
      console.log(foo, bar);
      // do something
    }
    
But I am unsure what the best approach is with desctructured function parameter. Do I just ignore the object, define it somehow or what is the best way of documenting it?

    /**
     * Description of the function
     *
     * @param {String} foo
     * @param {Boolean} [bar] - Optional value
     * @return {String}
     */
    function doSomething ({ foo, bar } = {}) {
      console.log(foo, bar);
      // do something
    }

I feel like my approach above doesn&#39;t make it obvious that the function expects an `object` and not two different parameter.

Another way I could think of would be using `@typedef`, but that might end up being a huge mess (especially in a larger file with many methods)? 

 
    /**
     * @typedef {Object} doSomethingConfiguration
     * @property {String} foo
     * @property {Boolean} [bar] - Optional value
     */

    /**
     * Description of the function
     *
     * @param {doSomethingConfiguration}
     * @return {String}
     */
    function doSomething ({ foo, bar } = {}) {
      console.log(foo, bar);
      // do something
    }

Document destructured function parameter in JSDoc

I am currently developing a NodeJS project and found out that there is no built in functionality to create JSDoc comments for functions/methods.

I am aware of the TypeScript definitions that exist but I couldn&#39;t really find anything to match what I need.

WebStorm, for example, has some pretty neat JSDoc functionalities. Can one somehow achieve a similar functionality?

Is there a way to generate JSDoc comments in Visual Studio Code

Is there a specified way to declare a method or a function to return void in JsDoc? Currently I am in the belief that `void` is the default return value, and other return values must be specifically provided:

    /**
     * @return {Integer} The identifier for ...
     */



How to return void in JsDoc?

I have some code that returns a promise object, e.g. using [Q](https://github.com/kriskowal/q) library for NodeJS.

&lt;!-- language: lang-js --&gt;

    var Q = require(&#39;q&#39;);
    
    /**
     * @returns ???
     */
    function task(err) {
        return err? Q.reject(new Error(&#39;Some error&#39;)) : Q.resolve(&#39;Some result&#39;);
    }

How to document such a return value using JSDoc?

How to specify resolution and rejection type of the promise in JSDoc?

Having next example:

&lt;!-- language: lang-js --&gt;

    var CONF = {
        locale: {
            &quot;en&quot;: {
                name: &quot;English&quot;,
                lang: &quot;en-US&quot;
            },
            &quot;es&quot;: {
                name: &quot;Spanish&quot;,
                lang: &quot;es-ES&quot;
            }
        }
    };

And knowing that what the locale property contains is a dictionary object, which comes from the database, how can I document its inner properties with JSDoc?

Currently I am thinking to ``typedef``  type for my locale objects, then may I be able to set the ``locale`` property to simply an Array of my defined type? Is this the right way to do it?


How to document a dictionary in JSDoc?

I&#39;ve spent quite a while scouring the internet looking for the best way to properly document callbacks with jsdoc, but unfortunately, I haven&#39;t found a great one yet.

Here&#39;s my question:

I&#39;m writing a Node.js library for developers. This library provides multiple classes, functions, and methods that developers will be working with.

In order to make my code clear and understandable, as well as to (hopefully) auto-generate some API documentation in the future, I&#39;ve started using [jsdoc][1] in my code to self-document what&#39;s happening.

Let&#39;s say I define a function like the following:

    function addStuff(x, y, callback) {
      callback(x+y);
    });

Using jsdoc, I&#39;m currently documenting this function as follows:

    /**
      * Add two numbers together, then pass the results to a callback function.
      *
      * @function addStuff
      * @param {int} x - An integer.
      * @param {int} y - An integer.
      * @param {function} callback - A callback to run whose signature is (sum), where
      *  sum is an integer.
      */
    function addStuff(x, y, callback) {
      callback(x+y);
    });

I feel like the above solution is kinda hack-ish, since there&#39;s no way for me to specify in absolute terms what the callback function should accept.

Ideally, I&#39;d like to do something like:

    /**
      * Add two numbers together, then pass the results to a callback function.
      *
      * @function addStuff
      * @param {int} x - An integer.
      * @param {int} y - An integer.
      * @param {callback} callback - A callback to run.
      * @param {int} callback.sum - An integer.
      */
    function addStuff(x, y, callback) {
      callback(x+y);
    });

The above seems like it&#39;d allow me to more simply convey what my callback needs to accept.  Does that make sense?

I guess my question is simple: what&#39;s the best way to clearly document my callback functions with jsdoc?

Thank you for your time.

  [1]: http://usejsdoc.org/

What&#39;s the proper way to document callbacks with jsdoc?

Let&#39;s say you have something like the following:

    var someFunc = function() {
        // do something here with arguments
    }

How would you correctly document that this function can take any number of arguments in JSDoc? This is my best guess, but I&#39;m not sure it&#39;s correct.

    /**
     * @param {Mixed} [...] Unlimited amount of optional parameters
     */
    var someFunc = function() {
        // do something here with arguments
    }

Related to: [php - How to doc a variable number of parameters][1]


  [1]: https://stackoverflow.com/questions/3590428/how-to-doc-a-variable-number-of-parameters

Correct way to document open-ended argument functions in JSDoc


    // My function does X and Y.
    // @params {object} parameters An object containing the parameters
    // @params {function} callback The callback function
    function(parameters, callback) {
    }

But how do I describe how the parameters object should be structured? For example it should be something like:

    {
      setting1 : 123, // (required, integer)
      setting2 : &#39;asdf&#39; // (optional, string)
    }

How to describe &quot;object&quot; arguments in jsdoc?

Edit: This is technically a 2 part question. I&#39;ve chosen the best answer that covers the question in general and linked 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) {
        }; 
    };

Neither the `PageRequest` object or the `callback` exist in code. They will be provided to `getPage()` at runtime. But I would like to be able to define what the object and function are.

I can get away with creating the `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&#39;s fine (though I&#39;m open to better ways to do this).

What is the best way to document the `callback` function? I want to make it know in the document that, for example, the callback function is in the form of:

    callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)

Any ideas how to do this? 

Best way to document anonymous objects and functions with jsdoc

Do you know if there is some sort of `&lt;code /&gt;` tag in JSDoc? I need to add pieces of code in my documentation like this:

    /**
     * This function does something see example below:
     *
     * var x = foo(&quot;test&quot;); //it will show &quot;test&quot; message
     *
     * @param {string} str: string argument that will be shown in message
     */
    function foo(str)
    {
       alert(str);
    }

I need the code in the comments to be displayed by JSDoc as code (if not syntax highlighted, at least like pre-formatted or something with grey background).

JSDoc adding real code in documentation

All of the official JSDoc examples have naively simple documentation strings, like the following:

    /**
     * @param {string} author - The author of the book.
     */

The problem is, in real-life documentation you often have longer documentation strings:

    /**
     * @param {string} author - The author of the book, presumably some person who writes well
     */

But since most companies (for legitimate readability reasons) have line length limits, the above often isn&#39;t acceptable.  However, what I can&#39;t figure out is what the &quot;right&quot; way of breaking up those lines should be.

I could do:

    /**
     * @param {string} author - The author of the book, presumably some
     * person who writes well
     */

But that is difficult to read.  I could instead do:

    /**
     * @param {string} author - The author of the book, presumably some
     *                          person who writes well
     */

That looks better, but it can result in a ton of lines, especially if the parameter has a long name:

    /**
     * @param {string} personWhoIsTheAuthorOfTheBook - The author of the
     *                                                 book, presumably
     *                                                 some person who
     *                                                 writes well
     */

So my question is, what is the proper/official/canonical way of formatting  long `@param` lines (in the code, not in the generated JSDoc) ... or really any long annotation lines for that matter.

What is the proper/canonical formatting of long JSDoc lines?

I want to be able to take JSDoc comments like this _anywhere_ in JavaScript source (even nested down several layers of functions, in a module or even anonymous functions):

    /**
     *  Used to do some important thing that needs doing that works like xyz.
     *  @param {String} whatever - some string that has some purpose
     *  @param {Function} callback - a function that needs to be run
     *  @returns {Boolean} whether or not something happened
     */
     function something(whatever, callback) {
         ...

and have some easy way to produce nice markdown:

    ##`root.something(whatever,callback)`
    Used to do some important thing that needs doing that works like xyz.
    
    *Parameters*
      `whatever {String}` some string that has some purpose
      `callback {Function}` a function that needs to be run

    *Returns*
       `{Boolean}` whether or not something happened

Where &quot;root&quot; is the namespace at which that function is reachable.  Or if it&#39;s an anonymous function or a private function (that for some reason should be in public doco, does that even make sense??), use some other convention to denote that.  Maybe

    ##_private_function_ `something(whatever,callback)`

      and

    ##_anonymous_function_`(whatever,callback)`

It doesn&#39;t have to be exactly that format, just something that looks good on Github and makes sense.  The ideal tool would be smart enough to be able to take code like [Mustache.js][1] and produce good output.  And extra good would be if it can handle lots of source files and produce one document as output, or a linked set of documents depending on configuration.

And it would be best if this was done in a way that can be fully and easily included in a git repo so that people don&#39;t need to set up a highly specific toolchain to update the doco.  Or require a minimal toolchain at least.

Oh, and a pony.

---

# Existing options

## [JSDoc][2], plus some kind of HTML -&gt; markdown conversion
JSDoc is pretty good.  But I can&#39;t seem to make it work well with modules.  Or rather, it&#39;s a bigger hassle than it ought to be IMHO.  I shouldn&#39;t need to add an extra tag to name the function.  I&#39;ve tried the @export and @name and still have trouble getting it to show up in the final doc the way I&#39;d want.  If someone can point to a JSDoc commented source that has modules in it and is done well, that might help.  **Update:** JSDoc v3 actually seems much better with modules than v2 so this might be a better fit.

Even if I could get JSDoc output like I want, I&#39;d need to convert from HTML to markdown.  I can&#39;t seem to find a good tool for that, does one exist?

## [Docdown][3]
I played a bit with Docdown but the fact it&#39;s PHP is kind of a nonstarter for me...

## [YUIDoc][4], plus conversion
I actually haven&#39;t played with YUIDoc but it looks ok.  Still, I would need a converter.  Does it deal with modules easily and avoid having to supply the function name and export name explicitly?

## [Dox][5], plus markdown templates
Dox produces JSON as it&#39;s output, so then you&#39;d need to marry that to some good markdown templates, and plus include a template engine to generate the documents.  Has anyone put together a set of such templates in a useful fashion?

## [jGrouse][6], plus conversion
Runs with ANT.  Next...

## ScriptDoc...
Does this even exist anymore?  Seems to be part of Aptana studio so that would be a nonstarter... Aptana doesn&#39;t seem to any info on it.  But ScriptDoc.org has some interesting information on crack, if that&#39;s helpful...

## [Pdoc][7]
Pdoc is Ruby based but that toolchain is not uncommon so that&#39;s not a huge problem.  You can provide your own templates so maybe there are already some good markdown ones.  I haven&#39;t played with it... is it worthwhile?  Are there good markdown templates out there?

## Something else?
What else is out there?

## Make your own!
After messing around with JSDoc for a few hours trying to make it work how I wanted, I gave up and [wrote my own quick and dirty solution in Java][8] for [CharFunk][9], a unicode JavaScript library I&#39;ve been working on.  It works well enough for what I need though it&#39;s not close to general purpose yet.

---

# So.....

Is this an unmet need or is it just me?


  [1]: https://github.com/janl/mustache.js/blob/master/mustache.js
  [2]: http://usejsdoc.org/
  [3]: https://github.com/jdalton/docdown
  [4]: http://yui.github.com/yuidoc/
  [5]: https://github.com/visionmedia/dox
  [6]: http://jgrouse.com/
  [7]: http://pdoc.org/
  [8]: https://github.com/joelarson4/CharFunk/blob/master/src/java/GenDoco.java
  [9]: https://github.com/joelarson4/CharFunk

How to easily create Github friendly markdown for documented JavaScript functions?

Is there a list somewhere of valid types for param tags for jsdoc? For example,

    @param {type} myParam Some parameter description

I know that things like `number` and `String` are valid, but what if I want to document that the number is an integer. Is `int` valid?

I&#39;ve done some googling, but I can&#39;t seem to find a full list.

jsdoc valid param types

I&#39;m trying to document an Express middleware, but the build-in validation tool in WebStorm tells me that types are incorrectly assigned in the following JSDoc block:

    /**
     * My middleware.
     *
     * @param {Object} req
     * @param {Object} res
     * @param {Function} next
     * @return {Object}
     */
    exports.show = function(req, res, next) {
        ...
    };

In Express sources, I didn&#39;t find any `@typedef`s to help me. Also, I want to avoid things like `@param {*}`.

What is the correct way to document Express middleware using JSDoc? Thanks for any help.

How to annotate Express middlewares with JSDoc?

While having parts of a Node.js in plain ES6, is it possible to mix in some Typescript modules within the same project?

E.g. having some Types defined in TypeScript that are imported via `require` into plain ES6 files?

All Jsdoc Solutions on Gang of Coders

Total of 19 Jsdoc Solutions