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).
