Range: comparePoint() method return not actually explained

[TAPgiles]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/Range/comparePoint

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

At the start of the page it says:

depending on whether the referenceNode is before, the same as, or after the Range.

What is meant by a specific point being the "same as" an entire range is not explained at all.

Edit: In fact "same as" is simply not correct. The value 0 means the point is "inclusively within the range". Could be the same as the start or end points of the range, but 0 doesn't mean the given point is the "same as" either of them necessarily.

The offset is not even mentioned in this opening explanation, making this an incomplete and confusing explanation. Then the offset is explained, but not how it relates to the "before/same as/after" concept.

This is the description of the offset parameter:

An integer greater than or equal to zero representing the offset inside the referenceNode.

In other words, "the offset is an offset." There is a better explanation in the opening to the page, but if you go straight to the part you want to learn about, the offset section, there's nothing useful there.

The return value section says this:

Returns -1, 0, or 1.

With even less explanation as to what any of it means. And then unhelpful basic example code is given, that does not aid understanding.

What did you expect to see?

These concepts should actually be explained.

For readers to correctly and clearly understand the method, these things should be explained (probably in the return section, which is where it's relevant):

• "Before" (-1) means the point is within a node earlier in the document. Or within the same node with a lower offset than the start offset of the range.
• "Same as" (0) means the point is within the start container of the range, and at or after the start offset within that node. Or within a later node that is before the end container. Or within the end container of the range, and at or before the end offset within that node.
• "After" (1) means the point is within a node after the end container of the range. Or is the end container or within it, and has a higher offset than the end offset of the range.

For the offset, the explanation should at least be in the offset section. It can be the same elsewhere on the page, but if you use MDN as a reference and so skip straight to the thing you want to learn about you should be able to learn about it right there instead of needing to look over the whole page. The intro can be an introduction, that's fine. But to my thinking it shouldn't be the entire explanation that's then not used in the relevant sections on the page.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response