-
Notifications
You must be signed in to change notification settings - Fork 236
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 write a Ruby class
that implements the 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 the very simplest of tags that even a monkey can implement.
TODO...
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.
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;