The js2doc system finds comments to go with declarations by looking
for the closest comment before the declaration, like this:
/** Frobs the frobnitz, in order to gunk the gunklebots */
function frobFrobnitz() ....
In LzState.lzs, I just ran across a few places where a commented-out
override keyword was inserted between the doc comment and the
function declaration:
/** Frobs the frobnitz, in order to gunk the gunklebots */
/* override */ function frobFrobnitz() ...
I can tell that you're preparing for a cool compiler change, but
sadly, the js2doc tool can't find the lovely documentation in that
form. It just sees "override" which isn't even a doc comment.
It's arguable whether the doc tools sholuld skip over non-doc-
comments interspersed between doc comments and declarations, but for
the time being, it doesn't. So, to add something like override
without breaking the js2doc, it's necessary to do this:
/** Frobs the frobnitz, in order to gunk the gunklebots
override */ function frobFrobnitz() ...
This issue is particularly bad when the doc comment is trying to mark
a function private:
/** @access private
Defrobulate the ungulates. WARNING: THIS WILL DESTROY THE WORLD */
/* override */ __defrobulateUngulates() ...
because then the js2doc tool won't see the @access private
annotation, and will thus list __defrobulateUngulates in the
reference with no documentation whatsoever.
Tucker or Don, do you want to propose a better way of including the
override hint? I've got a bunch of changes to check in that address
this, so that we don't document, for instance, LzState.__LZstorerefs
(...) ... as a public api.
-ben
