New in jsduck 5
The new JSDuck 5.0 brings a brand new custom tags system, which replaces the severely limited meta-tags system introduced in JSDuck 3.
We have learned from your feedback on the old system and built a new one that eliminates all the limitations that were stopping you from extending JSDuck the way you wanted.
So you can now use advanced ways for parsing the tag data from documentation, create your own custom member types, override the behaviour of builtin tags, and style your generated HTML with easy-to-include CSS.
But most importantly the new tags system is also used internally by JSDuck to implement most of its builtin tags. So your custom tags can really take advantage of all the same capabilities that JSDuck itself uses.
See the Custom tags guide in JSDuck wiki.
JSDuck 5 brings two considerable changes to the layout of exported JSON.
The largest change is how class members get listed. In JSDuck 4 they were split into "members" and "statics" and inside that there were subsections for each member type:
{
"tagname": "class",
"members": {"method": [...], "event": [...]},
"statics": {"method": [...], "event": [...]}
}
In JSDuck 5 this has been changed to simple array:
{
"tagname": "class",
"members": [...],
}
So if you're only interested in particular type of members, it's up to you to filter out members by type (using the "tagname" field) or separate instance and static members (using the "static" field).
Another change is that inside member hashes there is no "meta" field any more. Instead all these meta-fields are now available directly inside the member hash. So when in JSDuck 4 export you saw:
{"tagname": "method", "meta": {"protected": true}}
In JSDuck 5 you will now see:
{"tagname": "method", "protected": true}
Previously JSDuck used Esprima, which is a JavaScript parser written in JavaScript. But because JSDuck itself is written in Ruby, it also had to include a V8 runtime. All this resulted in lots of dependencies which complicated the installation process and the embedding of V8 wasn't stable enough, resulting in random crashes.
JSDuck 5 replaces all this with pure-Ruby JavaScript parser RKelly, which has been custom-tuned to work with JSDuck.
There's now a neat way to scope warnings by path.
Say, you're building your app on top of old Ext 3, so you run JSDuck like this:
$ jsduck ext3/src myapp/src --output somedir
But Ext3 is an old code-base and JSDuck will give you lots of
warnings. You could specify --warnings=-all, but now you won't get
any warnings for your own project too.
In JSDuck 5 you can now say --warnings=-all:ext3/src and only the
warnings triggered by files in ext3/src will be turned off.
Lastly JSDuck 5 introduces two new tags:
-
@localdoc defines a documentation block that's not meant to be inherited with
@inheritdoc. This allows you to work around an often occuring situation where you want to inherit most of the documentation, except for one particular piece. -
@fires allows you to document which events get fired when a particular method is called. But you don't really need to use this tag much, because JSDuck is able to auto-detect lots of these events from your source code.