CODEWITHSUNDEEP
javascriptdocumentationtags
Ian Elliott
Ian Elliott

Reputation: 7686

Proper tags for objects in jsdoc

What is the proper way to document objects of this style in jsdoc:

/**

*/

var strings = 
{
    /**

    */  
    stripHTML: function(html)
    {
        //does something
    },
    /**

    */
    validHTML: function(html)
    {
        //does something else
    }
}

Namely the proper parameter to define the object, and to recognize the sub-functions as part of 'strings'. I know about @param, @return etc, I just don't know the main definition for this type of object.

Upvotes: 3

Views: 1358

Answers (2)

Billy Moon
Billy Moon

Reputation: 58521

Although there are good arguments for defining object member functions by setting prototype, sometimes that is not practical. I thought I would post an answer that does not re-factor the code. It uses the same idea as @Jonathan's answer.

/**
 * @namespace
 * Custom String functions
 */
var strings = 
{
    /**
     * Strips the HTML away
     */  
    stripHTML: function(html)
    {
        //does something
    },

    /**
     * Ensures the HTML is valid
     */
    validHTML: function(html)
    {
        //does something else
    }
}

The example from: JSDoc-Toolkit was exactly what I was after.

Upvotes: 2

Jonathan Fingland
Jonathan Fingland

Reputation: 57167

I would use @namespace for "strings"

the methods would simply use @function (though it's obvious to jsdoc what they are

Edit In your particular example you may want to use something like:

/**
    describe purpose
*/
String.prototype.stripHTML = function()
{
    //does something with this
}

/**
    describe purpose
*/
String.prototype.validHTML = function()
{
    //does something else with this
}

then used like this:

var str = "bob<br/>";
str = str.stripHTML();

Upvotes: 2

Related Questions