api.Element.replaceWith - Misleading details and prototype

[WebReflection]

What type of issue is this?

Other

What information was incorrect, unhelpful, or incomplete?

As you correctly link to the standard, replaceWith is a ChildNode mixin and not an Element method.

That means that even text nodes or comments can use replaceWith while not being instanceof Element.

This is rather a misleading link in MDN, but also changing it would kinda rot such misleading information, so something must change though, as the info is everything but reliable or accurate.

What browsers does this problem apply to, if applicable?

No response

What did you expect to see?

At least a link to ChildNode mixin, but also nothing strictly related to Element prototype.

Did you test this? If so, how?

document.createComment('').replaceWith ; // function
document.createComment('') instanceof Element; // false

Can you link to any release notes, bugs, pull requests, or MDN pages related to this?

https://dom.spec.whatwg.org/#interface-childnode

Do you have anything more you want to share?

No response

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceWith

MDN metadata

MDN page report details

• Query: api.Element.replaceWith
• Report started: 2022-10-11T19:41:59.573Z

[queengooborg]

What are you expecting to see instead of what is currently written? Are you looking to see pages created for "Node.replaceWith" and "Comment.replaceWith"?

A while back, we had stripped out all mixins from MDN and merged their members into the interfaces that use them, as documenting them separately caused more reader confusion and was much harder to properly maintain the BCD for.

[WebReflection]

@queengooborg I am expecting to see a mention about being available on CharacterData too so that anyone landing on Element, as that's what most developers use as reference, would instantly recognize the method usable with text and comments too. The page is already there so maybe this is an easy improvement? Thanks.

[pygy]

As far as I can tell, the ChildNode mixin is mixed into Node, not Element. That's why it also applies to TextNode and Comment

I think that .after(), .before(), .remove() and .replaceWith() should thus be moved to Node.

[WebReflection]

@pygy that's fair but to me a bit misleading because even attributes are nodes but that mixin doesn't apply ... so, technically speaking, I think the mixin related page should be the best for everyone, but surely Element only, as it is, feels really off the MDN purpose itself, as it's quite misleading.

[pygy]

Oh, indeed, I had missed the CharacterData entry.

Conceptually, ChildNode could be defined as an abstract interface like CharacterData, (snuck as a Node child in the inheritance hierarchy).