Range: compareBoundaryPoints() method examples and explanation unclear

[TAPgiles]

MDN URL

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

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

In the list of how parameter values it speaks in terms of:

compares the end boundary-point of sourceRange to the start boundary-point of Range.

This is misleading. It seems as though it's saying the result will be source compared to arg. Which is not correct. I'd recommend that section should be rewritten to be clearer. (It's a shame the enum names are so confusing, but probably not much anyone can do about it now.)

The return value puts things in a different order:

indicating whether the corresponding boundary-point of the Range is respectively before, equal to, or after the corresponding boundary-point of sourceRange.

This, though technically accurate, is just plain hard to get your head around.

The example is just a very general code snippet that does not help the reader understand how the method works.

What did you expect to see?

Here's an example of how the how section could be rewritten:

how A constant describing the comparison method. The first part of the name indicates the boundary of the passed-in Range, which will be compared relative to the boundary of the source Range as indicated by the second part of the name.

• Range.END_TO_START: passed-in Range's end, relative to source's start.

Here's a possible different example that could be used. The goal with this version is to visually demonstrate the ranges involved, making it easy to see their relative start and end points, and associate that with how the method functions. Multiple example calls are included with their return values shown and explained. Clearer variable names are used that reflect how the two ranges are referred to in the (updated) text.

var text = new Text("0123456789");

var sourceRange = new Range();
sourceRange.setStart(text, 1); // the position after the 1st node/character
//                         v-----
//                        0 1 2 3 4 5 6 7 8 9
//                          ---------^
        sourceRange.setEnd(text, 6); // the position after the 6th node/character


var passedRange = new Range();
passedRange.setStart(text, 1); // the position after the 0th node/character
//                         v----
//                        0 1 2 3 4 5 6 7 8 9
//                         ------^
      passedRange.setEnd(text, 4); // the position after the 4th node/character

// The ranges compared so far...
// sourceRange start v---------v sourceRange end
//                  0 1 2 3 4 5 6 7 8 9
// passedRange start ^-----^ passRange end

// passed start is *same as* source start
sourceRange.compareBoundaryPoints(Range.START_TO_START, passedRange); // == 0 *same as*

// passed start is *after* source end
sourceRange.compareBoundaryPoints(Range.START_TO_END, passedRange); // == 1 *after*

// passed end is *after* source start
sourceRange.compareBoundaryPoints(Range.END_TO_START, passedRange); // == 1 *after*

// passed end is *before* source end
sourceRange.compareBoundaryPoints(Range.END_TO_END, passedRange); // == -1 *before*

It's a little harder to read on this site than it would be on MDN. Or some graphics could be made that are even easier to understand and just as clear.

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

No response

Do you have anything more you want to share?

No response