Refactor pointer events

[Elchi3]

This is a work item for #685.

Pages:

• https://developer.mozilla.org/en-US/docs/Web/Events/gotpointercapture
• https://developer.mozilla.org/en-US/docs/Web/Events/lostpointercapture
• https://developer.mozilla.org/en-US/docs/Web/Events/pointercancel
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerdown
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerenter
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerleave
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerlockchange
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerlockerror
• https://developer.mozilla.org/en-US/docs/Web/Events/pointermove
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerout
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerover
• https://developer.mozilla.org/en-US/docs/Web/Events/pointerup
• https://developer.mozilla.org/en-US/docs/Web/Events/MSPointerHover

The target interfaces here are document and element, so this is a case where there is not one redirect, but a split. We could decide to redirect to either document or element, though.

[wbamberg]

@Elchi3 , I think these pages are ready for you to take a look at:

https://developer.mozilla.org/en-US/docs/Web/API/Element#Events
https://developer.mozilla.org/en-US/docs/Web/API/Document#Events

Some notes:

• I didn't migrate https://developer.mozilla.org/en-US/docs/Web/Events/MSPointerHover since it only ever worked on IE and has now been deprecated. Shall we delete it?
• pointerlockchange and pointerlockerror are Document-only, and the corresponding on- properties, although they exist on the object, don't have docs pages. I haven't created docs pages for these on- properties.
• the other 10 are on both Document and Element, so I have duplicated the event pages for these two interfaces. The corresponding on- properties for these events are all defined on the GlobalEventHandlers interface and are documented there.

I've been having problems with Kuma, and in at least 2 places the page being shown doesn't reflect the latest revision:

• https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerenter_event (https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerenter_event$compare?locale=en-US&to=1459222&from=1459219)

• https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerout_event (https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerout_event$compare?locale=en-US&to=1459231&from=1459230)

:(

Thanks for looking!

[Elchi3]

@Elchi3 , I think these pages are ready for you to take a look at:
https://developer.mozilla.org/en-US/docs/Web/API/Element#Events
https://developer.mozilla.org/en-US/docs/Web/API/Document#Events

Thanks, Will!

A minor thing about the event listing that I see different from how I've done it:

pointercancel

Fired when a pointer event is canceled. Also available via the onpointercancel property.

For web speech events, I had put a <br> so that the event description stands out a little more:

pointercancel

Fired when a pointer event is canceled.
Also available via the onpointercancel property.

What do you think?

---

I didn't migrate https://developer.mozilla.org/en-US/docs/Web/Events/MSPointerHover since it only ever worked on IE and has now been deprecated. Shall we delete it?

I think if we mention on the pointermove pages that in IE11 an ancient MSPointerHover existed, we can totally delete the MSPointerHover page, but some people generally prefer archiving and we're lacking a policy, so I don't know :/

---

pointerlockchange and pointerlockerror are Document-only, and the corresponding on- properties, although they exist on the object, don't have docs pages. I haven't created docs pages for these on- properties.

That's fine with me, we have the red links to them. Maybe someone will create the pages at some point.

---

the other 10 are on both Document and Element, so I have duplicated the event pages for these two interfaces. The corresponding on- properties for these events are all defined on the GlobalEventHandlers interface and are documented there.

Thanks, this is an interesting case! GlobalEventHandlers, I think, isn't a thing that web developers normally see, but as we didn't want to duplicate all this stuff to Document, Window, Element, etc, we've created this mix-in page (and I suppose it is defined in WebIDL like this).
I guess our alternative would be, instead of duplicating pages to Document and Element, to put events under GlobalEventHandlers. However, I think I find that imprecise and somewhat weird, as (1) it isn't a thing web developers see directly, (2) the specs change and so targets get added and removed, (3) the compat story might be different for each event on a given target.
Now, you could argue that we already went down that path with mix-ins and by doing something different with events now makes us inconsistent with methods and properties docs, but basically I have the same opinion there: I would rather duplicate pages instead of mixing all this up at one weird place... What do you think about this whole matter?

---

I've been having problems with Kuma, and in at least 2 places the page being shown doesn't reflect the latest revision:

I've forced refreshed pages, and the latest version seems to appear now.

---

The pages look good to me. I think another benefit of having these pages "duplicated" now, is that you can actually have example code that is different (one operating on Element and the other operating on Document).
I think we're missing a spec table on the pages, but otherwise they look fine.
I wonder if we should link to "this same event but on other targets" either in the blue box or in see also.

Overall, great work, Will! Thanks for digging into the heart of MDN API docs where I think we still have many structural questions, but I hope it isn't too frustrating :)

[wbamberg]

For web speech events, I had put a
so that the event description stands out a little more:

Yeah, fair enough, I've put those in here.

I think if we mention on the pointermove pages that in IE11 an ancient MSPointerHover existed, we can totally delete the MSPointerHover page, but some people generally prefer archiving and we're lacking a policy, so I don't know :/

Good plan and done (deleted).

Thanks, this is an interesting case! GlobalEventHandlers, I think, isn't a thing that web developers normally see...

I'll comment on this at #951 since that seems to be where the action is.

I wonder if we should link to "this same event but on other targets" either in the blue box or in see also.

Oh I wondered about this actually. It feels a bit odd now to have that "Target objects" line in the blue box, when, well, it's now obvious that (say) Document is one of the targets, because the page is now under Document. It's even odder when there's only one target: (e.g. IDBRequest: success) Perhaps we should remove that line from these pages, and where there are multiple targets, add a line to "See also" like "Additional target interfaces: Element", or something?

[Elchi3]

Perhaps we should remove that line from these pages, and where there are multiple targets, add a line to "See also" like "Additional target interfaces: Element", or something?

I think would be a lot better, yes.
"See also"
"- This event on Element targets: foo event"

[Elchi3]

I think moving "Target objects" line from the blue box to "See also" and adding spec tables is all that is left to do here. I'm going to review the BCD.

[wbamberg]

Thanks @Elchi3 . I think I have done that, and also fixed the titles and fixed the table formatting as per #685 (comment)

[Elchi3]

Great work Will! I've merged the compat data, so once that's on prod (later today), we can refresh pages and close this.

[wbamberg]

BCD is deployed, and pages are updated. Thanks for the reviews!

[wbamberg]

#951 (comment)

I've updated the pages (I think) and filed mdn/browser-compat-data#3540 for the BCD.

[Elchi3]

I've merged the BCD and the pages look correct to me.