Finish InterfaceOverview macro about kumascript

[a2sheppy]

Good catch on the `<dl>` tags. I will see about fixing that right away.

…

On Thu, Apr 19, 2018 at 2:24 PM, ExE Boss ***@***.***> wrote: Also, this macro currently leaks unclosed <dl> tags, as can be seen here <https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel#Event_handlers> . — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#542 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABkL339zXNRVD7favuKLZ4Gq0wASOpzoks5tqNZQgaJpZM4RUa0P> .

-- Eric Shepherd Senior Technical Writer Mozilla Blog: http://www.bitstampede.com/ Twitter: http://twitter.com/sheppy Check my Availability <https://freebusy.io/[email protected]>

[jpmedley]

I generally like the idea but I'm concerned about usability. Let's say I'm reading child.doStuff() and I see a link that just says getStuff(). When I click on it I'm now on a page titled parent.getStuff(). This is potentially disorienting, especially if I'm new to development. I'm also now browsing in the parent context when it's the child I'm interested in.

To say this another way, I think labeling has to be done thoughtfully and carefully for this to work.

[a2sheppy]

@jpmedley - Those are good points, although I point out that in this case we're talking solely about the macro that generates a list of links with brief summaries for all the items in an interface and not about general in-context links.

Still, this is probably a good argument for keeping the inherited stuff and the things from mixins listed separately. Then you could have a list like:

---

Attributes

BarInterface provides the following attributes. In addition, it inherits attributes from the FooInterface interface and implements the Bingo and Bongo mixins.

barattrib1
     Summary of the first attribute implemented on BarInterface.
...
barattribN
     Summary of the last attribute implemented on BarInterface.

Inherited from FooInterface

fooattrib1
     Summary of the first attribute implemented on FooInterface.
...
fooattribN
     Summary of the last attribute implemented on FooInterface.

Implemented from the Bingo mixin

bingoattr1
     Summary of the attribute implemented from the Bingo mixin.

Implemented from the Bongo mixin

bongoattr1
     Summary of the attribute implemented from the Bongo mixin.

---

Of course, all the code terms in there are links to the appropriate section or page.

That way, all the information is available, hopefully without confusing users when links to go other interfaces or to mixins.

[ExE-Boss]

Also, this macro currently leaks unclosed <dl> tags, as can be seen here.