[Laszlo-dev] mixin support in doc

[P T Withington]

May I suggest that you also poll laszlo-user on these questions?

On 2008-05-06, at 11:02 EDT, Donald Anderson wrote:

> Support for mixins in doc is here.  There's a couple potential small  
> cleanups coming
> soon that raise some questions for you all.
>
> At the top right of every reference doc page there is 'Extends  
> someclass'
> When there are mixins, you'll now see 'With somemixin,  
> someothermixin'.
> (the names like somemixin are linked to the appropriate page).
> Would you prefer more verbose:  'With mixins somemixin,  
> someothermixin'
> Or to emphasize the keywords, perhaps lower case 'with':
> 'with somemixin, someothermixin'.   The last would make sense if we
> lower cased 'extends' also.

I like lowercase and brief.  I think the structure of the classes is  
an implementation detail, not really of interest to the LZX  
programmer, especially if we can get to Henry's suggestion where there  
is a single 'flat' listing of all methods available somehow.

> if a mixin does not contribute attributes (or events, functions),  
> should we show the title
> 'Attributes inherited from somemixin' with an empty list?
> That behavior (always show the title) is the same as that used for
> regular inheritence.  Should we always omit the title in this case  
> (and for inheritance
> with no attributes) too?

I see no point in the empty tables, I would eliminate them.

> FYI, 'implements' (interfaces) is not really known by the doc tools  
> AFAIK.
> But the fact that a class must implement all the methods says that  
> the methods
> are all there and potentially documented (but the doc is not pulled  
> from the interface).
> Perhaps that can be fixed someday.  I just wanted to clear this up  
> because
> this came up in discussion.

That would be nice.

A question I have:  If a method is an override, can I just leave out  
the documentation?  It seems to me I should not have to document the  
API of a method just because I am overriding it (although I should if  
it modifies the contract of the API in some way).