Sprints: Refactor pointer events

Created on 6 Feb 2019  路  10Comments  路  Source: mdn/sprints

This is a work item for #685.

Pages:

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.

NeedsTimeEst
Source
picture Elchi3

Most helpful comment

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

picture Elchi3 on 27 Feb 2019
👍2

All 10 comments

@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:

:(

Thanks for looking!

wbamberg picture wbamberg on 15 Feb 2019

@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 \
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 :)

Elchi3 picture Elchi3 on 18 Feb 2019

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 https://github.com/mdn/sprints/issues/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?

wbamberg picture wbamberg on 19 Feb 2019

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 picture Elchi3 on 20 Feb 2019

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.

Elchi3 picture Elchi3 on 20 Feb 2019

Thanks @Elchi3 . I think I have done that, and also fixed the titles and fixed the table formatting as per https://github.com/mdn/sprints/issues/685#issuecomment-465494987

wbamberg picture wbamberg on 21 Feb 2019

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

Elchi3 picture Elchi3 on 21 Feb 2019

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

wbamberg picture wbamberg on 21 Feb 2019
👍1

https://github.com/mdn/sprints/issues/951#issuecomment-467250743

I've updated the pages (I think) and filed https://github.com/mdn/browser-compat-data/pull/3540 for the BCD.

wbamberg picture wbamberg on 27 Feb 2019

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

Elchi3 picture Elchi3 on 27 Feb 2019
👍2
Was this page helpful?
0 / 5 - 0 ratings

Related issues

schalkneethling picture schalkneethling  路  5Comments
Elchi3 picture Elchi3  路  4Comments
wbamberg picture wbamberg  路  5Comments
mattiapontonio picture mattiapontonio  路  5Comments
mattiapontonio picture mattiapontonio  路  5Comments