booleanWithin and booleanContains documentation misleading, confusing
Nobody has claimed this yet.
- 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-withinshould (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
trueif no part offeature1's geometry is outside offeature2's geometry. This is equivalent tobooleanContains(feature2, feature1).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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