Custom tags

The upcoming JSDuck 5.0 brings a brand new custom tags system. It's much more flexible and powerful than the old system introduced in JSDuck 3.0, but it's not backwards compatible.

To introduce a new @tag, you'll need to implement a Ruby class extending from JsDuck::Tag::Tag. Then load the class into JSDuck using the --tags option:

$ jsduck --tags my_custom_tag.rb  ...other.options...

But don't be scared of Ruby. We'll start off with simple boolean tags, that even a monkey can implement.

• Boolean tags
• Single-line tags

TODO...

More about parsing

parse_doc gets passed an instance of JsDuck::Doc::Scanner, which it must use to perform the parsing. This Scanner is similar to Ruby builtin StringScanner, it remembers the position of a scan pointer (a position inside the string we're parsing). The scanning itself is a process of advancing the scan pointer through the string a small step at a time.

Let's visualize how this works. Here's the state of the Scanner at the time parse_doc gets called.

* @license GNU General Public License v3
           ^

The scan pointer (denoted as ^) has stopped at the beginning of the word "GNU". At that point we could look ahead to see what's coming, e.g. we could check if we're starting to parse a GNU license:

scanner.look(/GNU/)   # --> true

The look method performs a simple regex match starting at the position of our scan pointer, returning true when the regex matches. But just looking doesn't advance the scan pointer, that's what the match method is for:

scanner.match(/.*$/)  # --> "GNU General Public License v3"

match returns the actual string matching the regex and advances scan pointer to the position where the match ended:

* @license GNU General Public License v3
                                        ^

The Scanner class contains a bunch of other useful methods for parsing the docs, but look and match are really at the core of it, and for our @license tag purposes we have done enough of parsing and successfully extracted the name of the license.

At this point we need to return a hash with our gathered data - otherwise we would get a tag that simply gets ignored.

The hash must contain a :tagname field which must match up with the @tagname field we define in constructor. Anything else inside this hash is our custom data we store there for later processing - which in our case is just all the text that followed the @license tag.

Custom member types

Let's define a @constant tag. It should work pretty much like @property, but with the semantic difference of documenting unchangable values. For example:

/**
 * Acceleration of objects in Earth's gravitational field.
 * @constant
 */
var ACCELERATION = 9.80665;

TODO...