search

mdn / content

The content behind MDN Web Docs
https://developer.mozilla.org
Other
9.14k stars 22.47k forks source link

Issue with "Page Visibility API": … #622

Closed sgbeal closed 3 years ago

sgbeal commented 3 years ago

MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API

What information was incorrect, unhelpful, or incomplete?

The Document.hidden property is marked as deprecated, yet the example on how to use the API makes use of that property instead of the newer alternative.

Specific section or headline?

https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API#Properties_added_to_the_Document_interface

The deprecation notice is at the top of that section. The example is at the bottom.

What did you expect to see?

That the example shows current API usage rather than the deprecated usage. e.g. instead of:

if (document.hidden) { ...

It "should" say:

if ("hidden" === document.visibilityState) { ...

Did you test this? If so, how?

N/A. The example works as is but it's poor practice for the docs to preach one thing and practice another.

MDN Content page report details * Folder: `en-us/web/api/page_visibility_api` * MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API * GitHub URL: https://github.com/mdn/content/blob/master/files/en-us/web/api/page_visibility_api/index.html * Report started: 2020-12-24T07:22:05.564Z
hamishwillee commented 3 years ago

@sgbeal Would you be interested in making the required changes? You can edit the page by clicking the link at the bottom

image

FWIW I think you're right. The reason I'm suggesting you do this is that I assume you already have the test code created and can verify this works for the examples you change.

sgbeal commented 3 years ago

Hi, @hamishwillee,

If i sign up as a doc editor, that's a deep, dark rabbit hole i wouldn't be able to resist going down, so i must respectfully decline (writing API docs/user manuals is a bit of a hobby of mine, but i can't afford yet another side project). (Also, i'm a developer on the Fossil SCM project and avoid git like the plague.)

However, i do indeed have a working example of the non-deprecated API in (haha!) the Fossil SCM project:

https://fossil-scm.org/fossil/file?ci=b06442a621870ea9&name=src%2Fchat.js&ln=919-929

https://fossil-scm.org/fossil/file?ci=b06442a621870ea9&name=src%2Fchat.js&ln=455-461

That code (which simply changes the page title when new chat messages arrive when the tab is not active then resets it when the tab becomes active again) is known to work.

hamishwillee commented 3 years ago

Thanks @sgbeal - I completely understand :-). Hopefully someone will get to this in a timely manner!