In the version of the refguide that shipped in 4.0.0, I only
recognized a simple set of runtime tags: basically as2, dhtml. But in
looking into a bug related to documentation of LzTrack, I realized
that my model of things was too simplistic. LzTrack has a version for
$as2, but also a version for $js2, which js2doc totally ignores at
the moment.
After some investigation, I saw the problem. It appears as though
there is a set of explicit runtimes, and then a set of composite
runtimes:
simple: swf7, swf8, swf9, dhtml, svg, j2me
compound: as2, as3, js2
as2 === (swf7 || swf8 || swf9)
as3 === (swf9)
js2 === (dhtml || svg || j2me)
So I implemented a "runtime alias" feature is js2doc that basically
encodes these equalities. Whenever I see "as2", I act as though I had
seen "swf7 || swf8 || swf9".
This works well, and I now see the $js2-conditionalized entries for
LzTrack. There are a couple of problems, though.
One is that now everything that is tagged with $as2 in the sources is
now tagged with "swf7 swf8 swf9". A bit verbose, not as descriptive,
but maybe livable (except for the swf9 part! See my ps. below.)
Another is that the code tagged with $js2 in the sources comes out as
"dhtml svg j2me" in the reference. This makes me think that I should
be retaining the "composite" runtimes through the toolchain, but that
would be a much bigger code change and would introduce a lot more
complexity.
So I guess I'm asking for any thoughts on this from the folks who
designed the runtime designations. Can I get away with expanding the
composite runtime tags when I see them, or would it really be worth
the (considerable) trouble required to retain the composite tags?
jim
ps Are we going to get into trouble having swf9 being as as2 runtime?
Do we really want all the code conditionalized by $as2 to run in an
$as3 runtime as well?
