Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Range: comparePoint() method return not actually explained #35830

Open
TAPgiles opened this issue Sep 11, 2024 · 0 comments
Open

Range: comparePoint() method return not actually explained #35830

TAPgiles opened this issue Sep 11, 2024 · 0 comments
Labels
Content:WebAPI Web API docs help wanted If you know something about this topic, we would love your help!

Comments

@TAPgiles
Copy link

TAPgiles commented Sep 11, 2024

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

@TAPgiles TAPgiles added the needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. label Sep 11, 2024
@github-actions github-actions bot added the Content:WebAPI Web API docs label Sep 11, 2024
@Josh-Cena Josh-Cena added help wanted If you know something about this topic, we would love your help! and removed needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. labels Oct 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:WebAPI Web API docs help wanted If you know something about this topic, we would love your help!
Projects
None yet
Development

No branches or pull requests

2 participants