Range: comparePoint() method return not actually explained

[TAPgiles]

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

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? It is not explained at all.

The return value section says this:

Returns -1, 0, or 1.

With even less explanation as to what any of it means. And then the same kind of unhelpful example code is given.

For readers to correctly and clearly understand the method, these things should be explained:

• "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.

Also 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." This should describe what an offset actually is.

[pransh15]

Hi @TAPgiles 👋

Thank you for starting this discussion, and your effort and thought into making MDN better!

I would recommend that you file an issue under mdn/content for this, and this discussion as well. The reason I'm asking you to file an issue is because that invites discussions from all the authors and experts on MDN, and we can start a PR right away.

Feel free to let me know if you are face any problems creating an issue. :)

[TAPgiles]

Okay cool. I wasn't sure if "issues" were only bugs, but now I know this stuff is included I'll copy them to issues. Thanks 👍

[pransh15]

That's fair, @TAPgiles. Trust me - I've been there too. 😅
I would just go ahead and convert a discussion to an issue if GitHub would let me, but it only allows an issue to turn into a discussion. 😬

[TAPgiles]

Oh lol... I've made issues now anyway. Thanks for the help 👍

[TAPgiles]

Oh, a quick question... it seems like most of the range pages have similar problems to the ones outlined in these couple of posts. Is it okay to file an issue that applies to them all, or should each be a separate report?