Engineering Blog

We use JSDuck to document our JavaScript.  This is the same tool that Ext uses for its documentation.

A few days ago, I was looking through some of our JavaScript where we’d put comments that would be picked up by JSDuck when it creates the documentation that we use.

We had some config options that were incorrectly documented like this:

/**
 * @cfg {String} some string config with a default value
 */
defaultName: 'fooBar'

JSDuck would see ’some’ as the name of the config since it was the first word following the type (String) and ’some’ would show up in the documentation as a config option for the class that was being documented

I first fixed by putting the appropriate name of the config as the first word following the type:

/**
 * @cfg {String} defaultName Some string config with a default value
 */
defaultName: 'fooBar'

Then I noticed that some of the other configs in the same file were defined slightly differently; they didn’t have the name of the config in the comment, but the documentation was still generated correctly:

/**
 * @cfg {String}                                  <-----There's nothing else on this line!
 * Some string config with a default value
 */
defaultName: 'fooBar'

This works great because then you don’t have to copy/paste the name of the config option, JSDuck figures it out for you. Makes it a lot easier when/if the name of the config option gets changed because it won’t be hidden in a comment right above the declaration. Duplication is bad!!!!

At this point, I thought that I’d learned everything I’d ever need to know about JSDuck so I sent out an email to the other developers sharing my new-found knowledge (read: awesomeness )

That’s when the great Mr. Burke Webster added some more great points:

“If your config option has a default value and it’s a basic type, JSDuck will also auto-detect that. So you can do things like this:

/**
 * @cfg
 * Should do something cool
 */
doSomethingCool: true

It will auto-detect that doSomethingCool is a boolean, with a default value of true.

/**
 * @cfg
 * Some string config with a default value
 */
defaultName: 'fooBar'

It will auto-detect that defaultName is a String, with a default value of ‘fooBar’. And if you don’t want to provide a default value, make sure you use ‘undefined’:

/**
 * @cfg
 * A name config for some component
 */
name: undefined

If you try other empty (or falsy) values, like empty string or null, the docs will report the config option has a default value of null.”