Have the Great Mixin Debate

[Elchi3]

User story

As an MDN reader, I want to browse structured and consistent API reference docs, so I can learn about Web APIs effectively.

Acceptance criteria

A plan is written how "mixins" should be documented and appear in API docs and compat data going forward.

Tasks

• Research how mixins appear in WebIDL files
• Research how mixins are currently documented on MDN and in BCD
• List pain points and problems with the current approach to mixins (for both tech writers and MDN readers)
• Explore alternative ways to deal them.

[jpmedley]

See this for info related to bullet 1: #3949

[jpmedley]

I'm officially blocked by not having a resolution to this. I set out to work on the PaintRenderingContext2D interface, which is shown in the spec as entirely made of mixins. Chrome's implementation implements its properties and methods directly.

[Elchi3]

On MDN, we have https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D and all members are under this tree. I made this decision long time ago and also didn't follow the mixins that are present in the spec (https://html.spec.whatwg.org/multipage/canvas.html#2dcontext).

While we have no official resolution to this, I'd say you should go ahead and have the PaintRenderingContext2D page with the members below it and not break this down to all the mixins. Yes, this means that the member pages will be somewhat duplicated between CanvasRenderingContext2D and PaintRenderingContext2D, but in fact not really: The compat data will be different, the example code will be different, the spec reference will be different. So, I believe that API docs sometimes come with some duplication and while it is annoying to author them, I believe that this way offers the best experience for the reader.

I want to take time and properly research my assumption and then make the above the MDN standard, but I haven't had that time yet and in the past this proposal has been controversial in the team.

[jpmedley]

My inclination in this case was to duplicate. Thanks for the approval stamp.

[Elchi3]

See #1367 for how these discussions usually go.

[chrisdavidmills]

We are dealing with mixins elsewhere now, so I'm closing this; see mdn/content#1940