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.

Sign up for GitHub

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

Jump to bottom

Turf/Buffer - More precise documentation of supported units for buffering #2218

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Turf/Buffer - More precise documentation of supported units for buffering #2218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 22 additions & 9 deletions packages/turf-buffer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,36 @@

## buffer

Calculates a buffer for input features for a given radius. Units supported are miles, kilometers, and degrees.
Calculates a buffer for input features for a given radius. Units supported are:

* centimeters or centimetres
* degrees
* feet
* inches
* kilometers or kilometres
* meters, metres
* miles
* millimeters, millimetres
* nauticalmiles
* radians
* yards

When using a negative radius, the resulting geometry may be invalid if
it's too small compared to the radius magnitude. If the input is a
FeatureCollection, only valid members will be returned in the output
FeatureCollection - i.e., the output collection may have fewer members than
the input, or even be empty.

**Parameters**
### Parameters

- `geojson` **([FeatureCollection][1] \| [Geometry][2] \| [Feature][3]<any>)** input to be buffered
- `radius` **[number][4]** distance to draw the buffer (negative values are allowed)
- `options` **[Object][5]** Optional parameters (optional, default `{}`)
- `options.units` **[string][6]** any of the options supported by turf units (optional, default `"kilometers"`)
- `options.steps` **[number][4]** number of steps (optional, default `8`)
* `geojson` **([FeatureCollection][1] | [Geometry][2] | [Feature][3]\<any>)** input to be buffered
* `radius` **[number][4]** distance to draw the buffer (negative values are allowed)
* `options` **[Object][5]** Optional parameters (optional, default `{}`)

**Examples**
* `options.units` **[string][6]** any of the options supported by turf units (optional, default `"kilometers"`)
* `options.steps` **[number][4]** number of steps (optional, default `8`)

### Examples

```javascript
var point = turf.point([-90.548630, 14.616599]);
Expand All @@ -30,7 +43,7 @@ var buffered = turf.buffer(point, 500, {units: 'miles'});
var addToMap = [point, buffered]
```

Returns **([FeatureCollection][1] \| [Feature][3]&lt;([Polygon][7] \| [MultiPolygon][8])> | [undefined][9])** buffered features
Returns **([FeatureCollection][1] | [Feature][3]<([Polygon][7] | [MultiPolygon][8])> | [undefined][9])** buffered features

[1]: https://tools.ietf.org/html/rfc7946#section-3.3

Expand Down
13 changes: 12 additions & 1 deletion packages/turf-buffer/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,18 @@ import {
} from "@turf/helpers";

/**
* Calculates a buffer for input features for a given radius. Units supported are miles, kilometers, and degrees.
* Calculates a buffer for input features for a given radius. Units supported are:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think that this is still a useful thing to add to the docs? I'd be inclined to just point users towards the typescript autocomplete for this field. Otherwise I'm mostly just concerned about keeping this list up to date with the actual definition in @turf/helpers. Maybe that's a silly concern since we probably don't often get new units of length.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should definitely try to avoid repeatedly listing all the options in the individual packages.

There might have been autocomplete issues in the past due to .js/.dts/JSDoc inconsistencies. For example, some places have Units in the function definition, but then just string in the JSDoc. Hopefully as we weed out the last few JS packages that will self resolve.

For this case maybe we say, leave any mention of units off completely. What do you think @marcjansen and @mfedderly?

* * centimeters or centimetres
* * degrees
* * feet
* * inches
* * kilometers or kilometres
* * meters, metres
* * miles
* * millimeters, millimetres
* * nauticalmiles
* * radians
* * yards
*
* When using a negative radius, the resulting geometry may be invalid if
* it's too small compared to the radius magnitude. If the input is a
Expand Down