should keep *Event properties* section in api event pages? #487
Replies: 0 comments 1 reply
-
The reason was the following: When writing an event handler, a web developer must know the event name, the event target, and the parameters of the event object passed to the handler. That way, the web developers have all the relevant information together. Parameters and methods of I agree that the maintenance complexity is a bit higher since we could forget to update some pages in case of a change. The experience shows that adding new parameters to event objects is rare (less than once a year), so this complexity appears mostly when documenting a new event type. If we find this complex, it could also be eased with the assistance of a script in CI. Note that, in such cases, we try to put the web developer first before the ease of maintenance (unless something is unmaintainable and would be consistently wrong) |
Beta Was this translation helpful? Give feedback.
-
Currently, many api event pages would includes a Event Type section and Event properties section, like https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event, and as the template https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_event_subpage_template suggest
However, this brings a question that since Event properties section is updated by hand, its content updates may be ignored or forgot when the content of the event interface updates (like mdn/content#29760 which was not updated at first but was found and updated later)
This also brings a question that if the content of the event interface updates, the content of event need also be updated too, so if the event interface is used by many pages, it means many pages need also update (like mdn/content#30589, the update to
PointerEvent
interface page means 14 other event pages' update)And it is confusing that why only mention event properties, not mention event methods (and static properties and static methods)
Honestly, I admit that keep the Event properties section may help show some important information, but I wonder if it is worse to keep this section than just let readers to go to the event interface page
Previous discussion mdn/content#10544 brings the new API event page type, with some discussions of whether adding an Event properties section
See also #18700 , which suggest to remove the Event properties section
Beta Was this translation helpful? Give feedback.
All reactions