Range: compareBoundaryPoints() method examples and explanation unclear #732

TAPgiles · 2024-09-10T12:29:42Z

TAPgiles
Sep 10, 2024

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

While 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.)

Here's an example of how it 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.

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. As discussed, clearer writing of the how section would help with this. But this is also where examples are meant to come in to make sure it's super clear. The example is just code, with no explanation of what result is expected.

Here's a possible different example that could be used:

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*

(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.