[Laszlo-dev] doc question, how should we document, 'ondata' in LzDataset

[André Bargull]

The same goes for "LzDatapointer#ondata".
And there is apparently a doc-bug in LzDatapointer:
The original java-doc for "LzDatapointer#ondata", is currently used for 
"LzDatapointer#onDocumentChange", oops!

> Right now, unless you mark an overridden method as private the doc  
> will show up.  So, my rule of thumb is:
>
> If you are overriding a method but _not_ changing its contract (this  
> should almost always be the case), simply doc it as @access private so  
> that it will just show up as inherited (and the user can read the  
> inherited documentation).
>
> If you are overriding a method and changing its contract (this would  
> be unusual), then you should document the method and contrast it with  
> the overridden method.
>
> That's my 2p.
>
> On 2008-05-12, at 14:07 EDT, Henry Minsky wrote:
>
> >/ LzDataset has an ondata event, which happens to be inherited from  
> />/ LzNode.
> />/ The "ondata" event is documented therefore in LzNode,
> />/ but it would probably make sense to document it in LzDataset also,  
> />/ because
> />/ it has a slightly different meaning; in LzNode it
> />/ fires when the view's datapath updates, but in LzDataset, it is sent  
> />/ when
> />/ the data  in the dataset has loaded or changed.
> />/
> />/ I don't know if it is worth worrying about, but it seems like there  
> />/ ought to
> />/ be some way to document it both on LzDataset and LzNode.
> />/ Or maybe we should be sending a different event, since they aren't  
> />/ really
> />/ the same thing.
> />/
> />/
> />/ -- 
> />/ Henry Minsky
> />/ Software Architect
> />/ hminsky at laszlosystems.com <http://www.openlaszlo.org/mailman/listinfo/laszlo-dev>
> /