Usage

Generating Ext JS 4 docs

Generating the basic docs for Ext JS 4 is quite simple:

$ jsduck extjs/src --output docs

But running this command gives us loads of warnings. Like so:

Warning: extjs/src/selection/CellModel.js:21: No documentation for Ext.selection.CellModel
Warning: extjs/src/dd/DragTracker.js:155: No documentation for Ext.dd.DragTracker#mouseup
Warning: extjs/src/data/proxy/Ajax.js:244: {@link Ext.data.amf.Reader AMF Reader} links to non-existing class
Warning: extjs/src/data/Store.js:547: Unknown type Ext.util.MixedCollection/Ext.data.Store.PageMap
Warning: extjs/src/data/Model.js:1408: Unclosed HTML tag: <debug>
Warning: extjs/src/grid/RowEditor.js:45: Unopened HTML tag: <locale>
Warning: extjs/src/Img.js:21: Image Ext.Img/Ext.Img.png not found.
Warning: extjs/src/grid/plugin/DragDrop.js:21: {@link Boolean} links to non-existing class

Some of these we want to ignore, as they are simply problems in Ext JS documentation that we can't really do much about. Like the problem with missing documentation. So we turn off warnings for missing class and member documentation:

--warnings=-no_doc,-no_doc_member

Similarly we can disable warnings for a broken link to Ext.data.amf.Reader and reference to bogus type name Ext.data.Store.PageMap:

--warnings=-link,-type_name

But this way these warnings get turned off globally, what we really want is only disable them for the Ext JS source. So we scope each of these warnings to Ext JS path:

--warnings=-no_doc:extjs/src
--warnings=-no_doc_member:extjs/src
--warnings=-link:extjs/src
--warnings=-type_name:extjs/src

Then there are warnings for <debug> and <locale> tags. Ext JS uses these as pre-processor directives, but JSDuck thinks they're invalid HTML. We could just turn off warnings for broken HTML with --warnings=-html, but better yet, we can ignore problems with these specific HTML tags:

--ignore-html=locale,debug

Now, we're really left with an actual problem - missing image files. JSDuck can't locate them because we haven't told it where to look for images included with an {@img} tag. So we do:

--images=extjs/docs/images

And finally there's a problem with {@link Boolean} - Ext JS is referencing the JavaScript builtin Boolean class. So we include JSDuck's builtin docs for standard JavaScript classes.

--builtin-classes

Instead of listing all these options on command line, which has grown fairly long now, we can place them to a JSON config file instead:

{
    "--": "extjs/src",
    "--warnings": [
        "-no_doc:extjs/src",
        "-no_doc_member:extjs/src",
        "-link:extjs/src",
        "-type_name:extjs/src"
    ],
    "--ignore-html": [
        "locale",
        "debug"
    ],
    "--images": "extjs/docs/images",
    "--builtin-classes": true
}

And then we just point JSDuck to this config file:

$ jsduck --config extjs-conf.json --output docs

For additional info on all the different warnings types run jsduck --help=warnings.