[Laszlo-dev] inserting comments between declarations and doc comments

[Donald Anderson]

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:  dda at ddanderson.com
WWW:    http://www.ddanderson.com