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

[P T Withington]

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