How to document JSON-Paramters

[Luke]

Hi there,

if I have a function that takes a JSON-Object as parameter, how do I document it? What I mean is this:

/**
 * mySampleFunction does something
 * 
 * @param {json} options Can include 3 fields:
 *                       {String} name Some name
 *                       {Integer} age Age of a person or something
 *                       {String} likes 'Icecream' or 'Pizza'
 */

function mySampleFunction(options) {
  options = options || {};
  //...
}

But I think *that*s probably not the way to go.

Any help would be appreciated

Thanks,
Lukas

[Michael Mathews]

Hi Lukas,

Try this pattern:

/**

 * mySampleFunction does something

 * 

 * @param {HTMLElement} element

 * @param {json} options The options.

 *    @param {String} options.name Some name

 *    @param {Integer} options.age Age of a person or something

 *    @param {String} options.likes 'Icecream' or 'Pizza'

 */

function mySampleFunction(element, options) {

}

(The indenting is only for the humans, JSDoc doesn't care.)

Regards,

Michael

--
You received this message because you are subscribed to the Google Groups "JsDoc Toolkit Users" group.
To post to this group, send email to jsd...@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-2+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/jsdoc-2?hl=en.

[Terry Weiss]

But what if they don’t like ice cream or pizza? (snort!)

 

Seriously – should the type be {json} or {Object}? It’s a static object, not a string. I struggle with this question regularly in our libraries. Static objects aren’t classes, just objects and there really isn’t an effective documentary construct for them that I can see. Am I missing something? I end up calling them classes using @class, and there is a sense in which they are…

[Michael Mathews]

Hi Terry,

It's mathematically provable that all people who ever have, do now, or ever will exist like ice cream or pizza. I don't remember the exact proof, but I know it exists.

Secondly, I hadn't even noticed the type of json in there, I just copied and pasted. It's possible the OP has defined a class named "json" somewhere, but if not I agree with you that it should not mean a "JSON string". Personally I use {Object} as the type for my option params.

Looking ahead a bit, JSDoc 3 will support a special class-like thing called a @typedef (first documented by those Google people, here: http://code.google.com/closure/compiler/docs/js-for-compiler.html ). Using that you can document things that are used in as types. For example you could document an "optionObject" type if you wanted.

Regards,

Michael

[Terry Weiss]

That looks more like the C typedef which acts like a synonym. Would you consider what is coming in V3 to be appropriate for the following:

 

Assume I have some class that accepts options as a parameter that are driven by defaults.

 

MyThing = function(options){…} ;

 

The options can be overridden at call time: var o = new MyThing({likes: ‘iceCream’, foo: ‘bar’});

But I also allow the user to override the options globally by declaring

 

MyThing.Defaults = {

                likes: ‘pizza’,

                foo: null

};

 

So that at startup or initialization the user can just

MyThing.Defaults.likes = ‘cookies’ ;

 

Would it look like this?

 

/**

Does something

@class MyThing

@param {MyThing.Defaults} options The options…

*/

MyThing = function(options){

                var runtimeOptions = $.extend({},MyThing.Defaults, options) ;

} ;

 

/**

The defaults for MyThing

@typedef {MyThing.Defaults}

*/

MyThing.Defaults = {

                /**

@type {String}

                */

                likes: ‘pizza’,

                /**

@type {Number}

                */          

foo: null

};

[Michael Mathews]

Yes, in JSDoc 3 (but not JsDoc Toolkit) I expect that you will be able to document that in this way:

/**

 * Does something.

 * @class

 * @param {MyThing.Defaults} options The options.

 */

MyThing = function(options) {

    var runtimeOptions = $.extend({}, MyThing.Defaults, options);

};

 

/**

 * The defaults for MyThing

 * @typedef

 */

MyThing.Defaults = {

    /**

     * @type {String}

     * @default "pizza"

     */

    likes: 'pizza',

    

    /**

     * @type {?Number}

     * @default null

     */          

    foo: null

};

Unless anyone sees a better way and would like to propose that here. :)

[Terry Weiss]

@typedef does not imply @static, right?

[Michael Mathews]

That is a good question. My initial reaction would be that a non-static typedef would then be a @class right?

By that same token a static @typedef could just be a @namespace.

Maybe @typedef is not the right thing here?

I think what is needed is something to document parameters more fully than the @param tag allows.

[Terry Weiss]

Thinking out loud:

 

“non-static typedef would then be a @class right”

Yes, but, that is not what the google compiler seems to imply. That looks more like a pre-compiler directive – but I think I am reading that implementation too closely. I’m not sure the google compiler semantics are very different from #typedef. Based on what you have said regarding jsdoc, I think, though, you are right, if it is not static, I would need to use the “new” keyword to instantiate it, so it would be a class.

 

“a static @typedef could just be a @namespace.”

I disagree with that statement. Or, I should say that it is true only syntactically. The implied semantics of the namespace is that it is just container for classes or class-like things, whereas the construct we are talking about is more than just a container – or if you want to insist that it is a container, then you must accept that it contains things other than [just] classes.

 

The problem, of course, is that we are continuing to use functional (i.e., typedef)  and OO (i.e., namespace, classes, even static) lexicon for JS which is neither of those things and both of those things simultaneously.

 

I also think it is a mistake to think of these things under discussion as just parameters. They could exist anywhere at any time and be consumed by any other valid JS construct. For instance, in our library, we define namespaces for our classes to get them out of the global space and prevent collisions. But there are some runtime objects as well, and we mount them all in a single global variable, somewhat like jQuery’s $. At system startup, the structure of our variable (called “athena”) is well known and documentable. It is not a parameter. It contains only runtime instances of composite and atomic values.

 

The question is: what is that? It’s not a class, certainly not semantically. Even syntactically, you don’t instantiate it with a “new” keyword.  There is a sense in which it feels like a struct, but it’s not. And I can add to it at any time. For instance, if the core loads as:

 

athena = {

            services: new something,

            content: new otherthing,

            language: “en-US”

}

 

Then later, if I load module X, it may supplement athena to add athena.X = foobar.

 

So, here’s what we can say about it. It is static – in the sense that you don’t need to use a “new” keyword to use it. It is a composite structure in that it can hold any other type instance. It is scoped by its parent. It’s like a bag or bucket (or heaven help us, a firkin – yes, I have thesaurus.com open). But those terms carry baggage as well (pun intended).  

 

“bag”  or “container” probably come closest to the its actual use, since it is generally used as a convenience to reduce clutter and simplify signatures. If you consider it a pattern, then you would also have to consider a verb to allow for runtime supplementation – i.e., adding things to it at runtime.

Or it could just be a typedef. J