Turfjs / Turfjs/turf

booleanWithin and booleanContains documentation misleading, confusing

Open
#2,340 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs
Dominant language
TypeScript
Stars
10.5k
Forks
1k
Avg merge
1h 11m
Merged PRs (30d)
4

Description

boooleanWithin:

Boolean-within returns true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and, the interior and boundary of the primary (geometry a) must not intersect the exterior of the secondary (geometry b). Boolean-within returns the exact opposite result of the @turf/boolean-contains.

booleanContains:

Boolean-contains returns True if the second geometry is completely contained by the first geometry. The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a). Boolean-contains returns the exact opposite result of the @turf/boolean-within.

(Emphasis added)

This last sentence in both cases is pretty misleading. It reads, to me at least, as saying that booleanWithin(a, b) == !booleanContains(a,b). However, if a and b partially overlap, then both booleanWithin and booleanContains return false. And if a == b then both functions return true.

Other issues:

  • I find the language used here to be quite confusing - especially the interior/boundary/exterior bit. Do points and linestrings even have interiors?
  • The two geometries are referred to in four different ways, once each: first/second, primary/secondary, a/b, and feature1/feature2. I suggest it should just be "feature1's geometry"/"feature2's geometry".
  • The hyphenated name Boolean-contains/Boolean-within should (I think) either be camel case, or to fit the style of the other methods, not present: "Returns true if...".
  • I don't really understand what the point of "both geometries must intersect" is. In what case could the second part be true (a is not outside b) without the geometries intersecting? I can only think of the case where a is null, but that doesn't seem to be supported by these functions

So overall I'd suggest something like:

Boolean-within:

Returns true if no part of feature1's geometry is outside of feature2's geometry. This is equivalent to booleanContains(feature2, feature1).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the documentation for @turf/boolean-within and @turf/boolean-contains, then compare the current wording with the predicate behavior described in the issue. Revise the explanations to use consistent feature terminology and accurately describe the relationship between the two functions; done means the overlap, equality, and containment cases are no longer misleading.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.