Revise: Web APIs / HTMLDialogElement Docs

[leevigraham]

Description

• Rewrote html / javascript examples for consistency, added consistent log output.
• Added examples of returnValue in close and requestClose
• Added additional context around close requests (linking out to spec) and cancel events

The examples are now much simpler focussing on the api methods. I've removed a lot of form related cruft which may have been confusing to developers new to the APIs.

I'm pretty sure the examples were originally copied from https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#examples

If this PR is successful I'll start on consolidating the examples in the https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog docs.

Motivation

After finding a broken example in the docs (#42053) I found more inconsistencies in the examples across all the Web APIs / HTMLDialogElement docs.

Additional details

Questions for reviewers… this is my first major PR.

Is there a style guide for when to use links vs code blocks for api methods in related docs? I've seen examples of both returnValue, {{domxref("HTMLDialogElement.returnValue", "returnValue")}}, and {{domxref("HTMLDialogElement.returnValue")}}.

Is there a style guide for writing code examples? In this case I've stuck with id selectors from the first example I updated, this also makes selection a bit clearer for new developers IMO, but it also may set a bad precedent.

Should the details page for a property include more information that the property on the element page. Example: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby contained more information about how the property worked than the instance property: https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/closedBy. Should these docs be rewritten to reflect each other?

Related issues and pull requests

#42053

// ping @hamishwillee

[github-actions]

Preview URLs (12 pages)

• /en-US/docs/Web/API/HTMLDialogElement/cancel_event
• /en-US/docs/Web/API/HTMLDialogElement/close_event
• /en-US/docs/Web/API/HTMLDialogElement/close
• /en-US/docs/Web/API/HTMLDialogElement/closedBy
• /en-US/docs/Web/API/HTMLDialogElement/open
• /en-US/docs/Web/API/HTMLDialogElement/requestClose
• /en-US/docs/Web/API/HTMLDialogElement/returnValue
• /en-US/docs/Web/API/HTMLDialogElement/showModal
• /en-US/docs/Web/API/HTMLDialogElement/show
• /en-US/docs/Web/API/HTMLDialogElement
• /en-US/docs/Web/API/HTMLElement/beforetoggle_event
• /en-US/docs/Web/API/HTMLElement/toggle_event

External URLs (2)

URL: /en-US/docs/Web/API/HTMLDialogElement/cancel_event
Title: HTMLDialogElement: cancel event

• https://html.spec.whatwg.org/multipage/interaction.html (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/HTMLDialogElement/closedBy
Title: HTMLDialogElement: closedBy property

• https://html.spec.whatwg.org/multipage/interaction.html (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2025-11-29 09:16:22)

[wbamberg]

@hamishwillee , since you looked at the other one, you have better context for this one than me. But LMK if you don't have time and I will have a look.

[wbamberg]

Oh, but since you had some questions:

Is there a style guide for when to use links vs code blocks for api methods in related docs? I've seen examples of both returnValue, {{domxref("HTMLDialogElement.returnValue", "returnValue")}}, and {{domxref("HTMLDialogElement.returnValue")}}.

I'm not sure if there are strict rules here. I would link at least the first mention of the thing in the page, and probably the first mention of the thing in that section (i.e. in that example) but not any subsequent mentions. Whether I would include the interface in the link text or not would depend on how obvious it is from the context.

Is there a style guide for writing code examples? In this case I've stuck with id selectors from the first example I updated, this also makes selection a bit clearer for new developers IMO, but it also may set a bad precedent.

Yes! https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Code_style_guide. And it does actually cover this case:

Use classes for styling, and reserve IDs for non-CSS purposes, such as for use in JavaScript ...

...so I would say you are OK to use ID attributes here.

Should the details page for a property include more information that the property on the element page. Example: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby contained more information about how the property worked than the instance property: https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/closedBy. Should these docs be rewritten to reflect each other?

This came up quite recently. IMO we should have the detailed documentation on the HTML element page, because the DOM API property is just defined as a reflection of the HTML element. If we document it to the same level in both places we will end up with a LOT of duplication (there are hundreds of these pages).

[leevigraham]

I'm not sure if there are strict rules here. I would link at least the first mention of the thing in the page, and probably the first mention of the thing in that section (i.e. in that example) but not any subsequent mentions. Whether I would include the interface in the link text or not would depend on how obvious it is from the context.

I tired to stick to something like that.

If I'm referencing the same method on it's page it was code markup, If I'm referencing a property or method that relates to the element / interface I was using a link without the interface. If it was a property or method that didn't relate to the element / interface I was using a link with the interface. I didn't really see it as a problem if the same property / method was linked multiple times as it made it easier to navigate without going back up to the original reference.

so I would say you are OK to use ID attributes here.

Perfect. I see that the HTML guide says use kebab-case so I'll update the examples.

This came up quite recently. IMO we should have the detailed documentation on the HTML element page, because the DOM API property is just defined as a reflection of the HTML element.

Was there a GitHub discussion / ticket I can take a look at?

I can see it from both sides. DOM API properties are set as attributes. I think it's the case that all attributes have a matching DOM property, but not all DOM properties have a matching attribute?

There's always a page for the Element which lists the attributes in a section. This list could be quite long depending on the Element.

There's always a page for the DOM Property which is self contained.

My expectation is:

• The element page lists the attribute, gives a short, high-level description, and links to the DOM property.
• The DOM property page is the canonical place for the full behaviour, including defaults, state transitions, edge cases, and examples (this might not make sense for more declarative attributes like popover commandfor and command).

Therefore it makes more sense to me that the Element page is the overview of all the attributes with an overview of each attribute, and a link to the DOM Property to dig deeper. This would make the Element page more scannable / readable and allow for more examples on the DOM Property page.

If we document it to the same level in both places we will end up with a LOT of duplication (there are hundreds of these pages).

That I agree with :)

[leevigraham]

Updated all examples to use consistent kebab-case ids.

I've also realised to keep everything in this section consistent I'll also need to revise: https://github.com/mdn/content/blob/main/files/en-us/web/api/htmldialogelement/index.md

[wbamberg]

Was there a GitHub discussion / ticket I can take a look at?

It came up here: https://github.com/mdn/content/pull/40260/files/2d031a2511f2a2a2f2fa9cf770dc7df049925836#r2196957148 .

[leevigraham]

@hamishwillee @wbamberg This PR is ready for review.

I've rewritten all the examples for consistency. This mainly means:

• simplification, removing unused elements like forms when were specifically documenting js apis
• Adding a form example for the cancel related documentation
• clear naming for buttons, ids
• hidden logging javascript for output in docs

I've expanded the cancel event and return value docs with references to a the spec "close request"

[wbamberg]

@leevigraham , you don't need to merge main into this PR whenever main changes.