Hi Ben,
According to this:
http://www.openlaszlo.org/lps4/docs/contributors/bk01pt03ch08.html
there's a way to handle it in js2doc, as @modifiers override
Tucker, are we planning to add this as a keyword?
- Don
On Nov 22, 2007, at 2:27 PM, Benjamin Shine wrote:
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
--
Don Anderson
Java/C/C++, Berkeley DB, systems consultant
Voice: 617-547-7881
Email: [EMAIL PROTECTED]
WWW: http://www.ddanderson.com
