Here we are again talking about mixins :) There isn't actually an issue on mdn/content yet that will formally decide about mixins, so I'm opening this one. Fun fun fun!

Please also read mdn/browser-compat-data#472 for prior discussions.
And if you are concerned about how inheritance structures (as opposed to mixins) are documented, then please read #1006.

So, observing mixins in the wild and deciding how to document them. I recently chatted to Rachel Andrew about this and here's what my take has been:

The idea is to document Aria attributes. A spec for them is here https://www.w3.org/TR/wai-aria-1.2/#AriaAttributes and the idl looks like this:

interface mixin AriaAttributes {
  attribute DOMString? ariaActiveDescendant;
  attribute DOMString? manymoreattributes;
}

Element includes AriaAttributes;

Now, as an MDN writer who uses WebIDL heavily to determine how and where to document things, you are not given a guideline where to document ariaActiveDescendant and friends, and so there are two options basically:

1. Create a new API tree called AriaAttributes and put it there: docs/Web/API/AriaAttributes/ariaActiveDescendant
2. Create a new page under the Element page tree: docs/Web/API/Element/ariaActiveDescendant

Option 1. exposes the mixin to the world of web developers and option 2. hides this abstraction.

I recommended option 2. and so why did I do that?

• Mixins are abstractions that aren't exposed or observed directly. They are specification or browser-engine implementation helpers.
• Browsers and specs use mixins to make their life easier and they rename, remove, re-organize them at their discretion. Documentation can't easily follow this. Example in case: In a later spec (https://rawgit.com/w3c/aria/master/#ARIAMixin), there is no AriaAttributes anymore, it is now called ARIAMixin. Consequently, with option 1. the page would need to move to docs/Web/API/ARIAMixin/ariaActiveDescendant and BCD would need to be updated, etc. But why? It doesn't really matter to web developers because Element.ariaActiveDescendant is going to be there no matter where in the spec or in IDL it has been defined.

On MDN, we can find API docs that do not hide the mixins however. Why is that? Example:

• https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope
• Side note for this one: google search suggestion I get here is "windoworworkerglobalscope is not defined", so people are trying to call it, but it doesn't exist!
• See also https://stackoverflow.com/questions/43402321/is-settimeout-located-somewhere-besides-window"

So, I guess the idea here is that mixins add features to multiple interfaces and so having to duplicate docs for every interface they appear on, should be avoided. Does that make sense, though? Mixins can disappear and be renamed still. Even in this case the docs make it quite confusing to the readers.

Feedback welcome.