diff --git a/documentation.yml b/documentation.yml index 9bd89b734..5fa9bcfab 100644 --- a/documentation.yml +++ b/documentation.yml @@ -1,165 +1,166 @@ toc: - - name: Measurement - - along - - area - - bbox - - bboxPolygon - - bearing - - center - - centerOfMass - - centroid - - destination - - distance - - envelope - - length - - midpoint - - pointOnFeature - - polygonTangents - - pointToLineDistance - - rhumbBearing - - rhumbDestination - - rhumbDistance - - square - - greatCircle - - name: Coordinate Mutation - - cleanCoords - - flip - - rewind - - round - - truncate - - name: Transformation - - bboxClip - - bezierSpline - - buffer - - circle - - clone - - concave - - convex - - difference - - dissolve - - intersect - - lineOffset - - polygonSmooth - - simplify - - tesselate - - transformRotate - - transformTranslate - - transformScale - - union - - voronoi - - name: Feature Conversion - - combine - - explode - - flatten - - lineToPolygon - - polygonize - - polygonToLine - - name: Misc - - kinks - - lineArc - - lineChunk - - lineIntersect - - lineOverlap - - lineSegment - - lineSlice - - lineSliceAlong - - lineSplit - - mask - - nearestPointOnLine - - sector - - shortestPath - - unkinkPolygon - - name: Helper - - featureCollection - - feature - - geometryCollection - - lineString - - multiLineString - - multiPoint - - multiPolygon - - point - - polygon - - name: Random - - randomPosition - - randomPoint - - randomLineString - - randomPolygon - - name: Data - - sample - - name: Interpolation - - interpolate - - isobands - - isolines - - planepoint - - tin - - name: Joins - - pointsWithinPolygon - - tag - - name: Grids - - hexGrid - - pointGrid - - squareGrid - - triangleGrid - - name: Classification - - nearestPoint - - name: Aggregation - - collect - - clustersDbscan - - clustersKmeans - - name: Meta - - coordAll - - coordEach - - coordReduce - - featureEach - - featureReduce - - flattenEach - - flattenReduce - - getCoord - - getCoords - - getGeom - - getType - - geomEach - - geomReduce - - propEach - - propReduce - - segmentEach - - segmentReduce - - getCluster - - clusterEach - - clusterReduce - - name: Assertions - - collectionOf - - containsNumber - - geojsonType - - featureOf - - name: Booleans - - booleanClockwise - - booleanConcave - - booleanContains - - booleanCrosses - - booleanDisjoint - - booleanEqual - - booleanIntersects - - booleanOverlap - - booleanParallel - - booleanPointInPolygon - - booleanPointOnLine - - booleanTouches - - booleanWithin - - name: Unit Conversion - - bearingToAzimuth - - azimuthToBearing - - convertArea - - convertLength - - degreesToRadians - - lengthToRadians - - lengthToDegrees - - radiansToLength - - radiansToDegrees - - toMercator - - toWgs84 + Measurement: + - along + - area + - bbox + - bboxPolygon + - bearing + - center + - centerOfMass + - centroid + - destination + - distance + - envelope + - length + - midpoint + - pointOnFeature + - polygonTangents + - pointToLineDistance + - rhumbBearing + - rhumbDestination + - rhumbDistance + - square + - greatCircle + Coordinate Mutation: + - cleanCoords + - flip + - rewind + - round + - truncate + Transformation: + - bboxClip + - bezierSpline + - buffer + - circle + - clone + - concave + - convex + - difference + - dissolve + - intersect + - lineOffset + - polygonSmooth + - simplify + - tesselate + - transformRotate + - transformTranslate + - transformScale + - union + - voronoi + Feature Conversion: + - combine + - explode + - flatten + - lineToPolygon + - polygonize + - polygonToLine + Misc: + - kinks + - lineArc + - lineChunk + - lineIntersect + - lineOverlap + - lineSegment + - lineSlice + - lineSliceAlong + - lineSplit + - mask + - nearestPointOnLine + - sector + - shortestPath + - unkinkPolygon + Helper: + - featureCollection + - feature + - geometryCollection + - lineString + - multiLineString + - multiPoint + - multiPolygon + - point + - polygon + Random: + - randomPosition + - randomPoint + - randomLineString + - randomPolygon + Data: + - sample + Interpolation: + - interpolate + - isobands + - isolines + - planepoint + - tin + Joins: + - pointsWithinPolygon + - tag + Grids: + - hexGrid + - pointGrid + - squareGrid + - triangleGrid + Classification: + - nearestPoint + Aggregation: + - collect + - clustersDbscan + - clustersKmeans + Meta: + - coordAll + - coordEach + - coordReduce + - featureEach + - featureReduce + - flattenEach + - flattenReduce + - getCoord + - getCoords + - getGeom + - getType + - geomEach + - geomReduce + - propEach + - propReduce + - segmentEach + - segmentReduce + - getCluster + - clusterEach + - clusterReduce + Assertions: + - collectionOf + - containsNumber + - geojsonType + - featureOf + Booleans: + - booleanClockwise + - booleanConcave + - booleanContains + - booleanCrosses + - booleanDisjoint + - booleanEqual + - booleanIntersects + - booleanOverlap + - booleanParallel + - booleanPointInPolygon + - booleanPointOnLine + - booleanTouches + - booleanWithin + Unit Conversion: + - bearingToAzimuth + - azimuthToBearing + - convertArea + - convertLength + - degreesToRadians + - lengthToRadians + - lengthToDegrees + - radiansToLength + - radiansToDegrees + - toMercator + - toWgs84 paths: GeoJSON: "https://tools.ietf.org/html/rfc7946#section-3" + GeoJsonProperties: "https://tools.ietf.org/html/rfc7946#section-3.2" GeometryCollection: "https://tools.ietf.org/html/rfc7946#section-3.1.8" Point: "https://tools.ietf.org/html/rfc7946#section-3.1.2" Points: "https://tools.ietf.org/html/rfc7946#section-3.1.2" diff --git a/packages/turf-along/README.md b/packages/turf-along/README.md index e172218e8..fe244f68e 100644 --- a/packages/turf-along/README.md +++ b/packages/turf-along/README.md @@ -8,11 +8,11 @@ Takes a [LineString][1] and returns a [Point][2] at a specified distance along t ### Parameters -* `line` **[Feature][3]<[LineString][1]>** input line +* `line` **([Feature][3]<[LineString][1]> | [LineString][1])** input line * `distance` **[number][4]** distance along the line -* `options` **[Object][5]?** Optional parameters +* `options` **[Object][5]?** Optional parameters (optional, default `{}`) - * `options.units` **[string][6]** can be degrees, radians, miles, or kilometers (optional, default `"kilometers"`) + * `options.units` **Units** can be degrees, radians, miles, or kilometers (optional, default `"kilometers"`) ### Examples @@ -38,8 +38,6 @@ Returns **[Feature][3]<[Point][2]>** Point `distance` `units` along the line [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String - --- diff --git a/packages/turf-along/index.ts b/packages/turf-along/index.ts index f881729b6..15cb0d167 100644 --- a/packages/turf-along/index.ts +++ b/packages/turf-along/index.ts @@ -8,11 +8,11 @@ import { getGeom } from "@turf/invariant"; /** * Takes a {@link LineString} and returns a {@link Point} at a specified distance along the line. * - * @name along - * @param {Feature} line input line + * @function + * @param {Feature|LineString} line input line * @param {number} distance distance along the line * @param {Object} [options] Optional parameters - * @param {string} [options.units="kilometers"] can be degrees, radians, miles, or kilometers + * @param {Units} [options.units="kilometers"] can be degrees, radians, miles, or kilometers * @returns {Feature} Point `distance` `units` along the line * @example * var line = turf.lineString([[-83, 30], [-84, 36], [-78, 41]]); diff --git a/packages/turf-angle/index.ts b/packages/turf-angle/index.ts index 8eb2dd914..9f6d328d3 100644 --- a/packages/turf-angle/index.ts +++ b/packages/turf-angle/index.ts @@ -6,7 +6,7 @@ import { rhumbBearing } from "@turf/rhumb-bearing"; * Finds the angle formed by two adjacent segments defined by 3 points. The result will be the (positive clockwise) * angle with origin on the `startPoint-midPoint` segment, or its explementary angle if required. * - * @name angle + * @function * @param {Coord} startPoint Start Point Coordinates * @param {Coord} midPoint Mid Point Coordinates * @param {Coord} endPoint End Point Coordinates diff --git a/packages/turf-area/index.ts b/packages/turf-area/index.ts index 3b0c7a1d5..ff016ec7b 100644 --- a/packages/turf-area/index.ts +++ b/packages/turf-area/index.ts @@ -5,7 +5,7 @@ import { geomReduce } from "@turf/meta"; /** * Calculates the geodesic area in square meters of one or more polygons. * - * @name area + * @function * @param {GeoJSON} geojson input polygon(s) as {@link Geometry}, {@link Feature}, or {@link FeatureCollection} * @returns {number} area in square meters * @example diff --git a/packages/turf-bbox-clip/index.ts b/packages/turf-bbox-clip/index.ts index 8d9221a5b..765dc3942 100644 --- a/packages/turf-bbox-clip/index.ts +++ b/packages/turf-bbox-clip/index.ts @@ -22,7 +22,7 @@ import { lineclip, polygonclip } from "./lib/lineclip.js"; * [lineclip](https://github.com/mapbox/lineclip). * May result in degenerate edges when clipping Polygons. * - * @name bboxClip + * @function * @param {Feature} feature feature to clip to the bbox * @param {BBox} bbox extent in [minX, minY, maxX, maxY] order * @returns {Feature} clipped Feature diff --git a/packages/turf-bbox-polygon/README.md b/packages/turf-bbox-polygon/README.md index f0368d043..7e99be723 100644 --- a/packages/turf-bbox-polygon/README.md +++ b/packages/turf-bbox-polygon/README.md @@ -11,8 +11,8 @@ Takes a bbox and returns an equivalent [polygon][1]. * `bbox` **[BBox][2]** extent in \[minX, minY, maxX, maxY] order * `options` **[Object][3]** Optional parameters (optional, default `{}`) - * `options.properties` **Properties** Translate properties to Polygon (optional, default `{}`) - * `options.id` **([string][4] | [number][5])** Translate Id to Polygon (optional, default `{}`) + * `options.properties` **[GeoJsonProperties][4]** Translate properties to Polygon (optional, default `{}`) + * `options.id` **([string][5] | [number][6])** Translate Id to Polygon (optional, default `{}`) ### Examples @@ -25,7 +25,7 @@ var poly = turf.bboxPolygon(bbox); var addToMap = [poly] ``` -Returns **[Feature][6]<[Polygon][1]>** a Polygon representation of the bounding box +Returns **[Feature][4]<[Polygon][1]>** a Polygon representation of the bounding box [1]: https://tools.ietf.org/html/rfc7946#section-3.1.6 @@ -33,11 +33,11 @@ Returns **[Feature][6]<[Polygon][1]>** a Polygon representation of the bounding [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[4]: https://tools.ietf.org/html/rfc7946#section-3.2 -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[6]: https://tools.ietf.org/html/rfc7946#section-3.2 +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/packages/turf-bbox-polygon/index.ts b/packages/turf-bbox-polygon/index.ts index 7da8fd1ee..6ae88a4a4 100644 --- a/packages/turf-bbox-polygon/index.ts +++ b/packages/turf-bbox-polygon/index.ts @@ -4,10 +4,10 @@ import { polygon, Id } from "@turf/helpers"; /** * Takes a bbox and returns an equivalent {@link Polygon|polygon}. * - * @name bboxPolygon + * @function * @param {BBox} bbox extent in [minX, minY, maxX, maxY] order * @param {Object} [options={}] Optional parameters - * @param {Properties} [options.properties={}] Translate properties to Polygon + * @param {GeoJsonProperties} [options.properties={}] Translate properties to Polygon * @param {string|number} [options.id={}] Translate Id to Polygon * @returns {Feature} a Polygon representation of the bounding box * @example diff --git a/packages/turf-bbox/index.ts b/packages/turf-bbox/index.ts index f3a414368..ddfe803c3 100644 --- a/packages/turf-bbox/index.ts +++ b/packages/turf-bbox/index.ts @@ -6,7 +6,7 @@ import { coordEach } from "@turf/meta"; * Calculates the bounding box for any GeoJSON object, including FeatureCollection. * Uses geojson.bbox if available and options.recompute is not set. * - * @name bbox + * @function * @param {GeoJSON} geojson any GeoJSON object * @param {Object} [options={}] Optional parameters * @param {boolean} [options.recompute] Whether to ignore an existing bbox property on geojson diff --git a/packages/turf-bearing/index.ts b/packages/turf-bearing/index.ts index 6d72bdc60..b7b8050a3 100644 --- a/packages/turf-bearing/index.ts +++ b/packages/turf-bearing/index.ts @@ -8,7 +8,7 @@ import { getCoord } from "@turf/invariant"; * Takes two {@link Point|points} and finds the geographic bearing between them, * i.e. the angle measured in degrees from the north line (0 degrees) * - * @name bearing + * @function * @param {Coord} start starting Point * @param {Coord} end ending Point * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-bezier-spline/index.ts b/packages/turf-bezier-spline/index.ts index 1334bbfc6..99599877b 100644 --- a/packages/turf-bezier-spline/index.ts +++ b/packages/turf-bezier-spline/index.ts @@ -10,7 +10,7 @@ import { Spline } from "./lib/spline.js"; * * The bezier spline implementation is by [Leszek Rybicki](http://leszek.rybicki.cc/). * - * @name bezierSpline + * @function * @param {Feature} line input LineString * @param {Object} [options={}] Optional parameters * @param {Object} [options.properties={}] Translate properties to output diff --git a/packages/turf-boolean-clockwise/index.ts b/packages/turf-boolean-clockwise/index.ts index a0579731e..16ae29c2f 100644 --- a/packages/turf-boolean-clockwise/index.ts +++ b/packages/turf-boolean-clockwise/index.ts @@ -4,7 +4,7 @@ import { getCoords } from "@turf/invariant"; /** * Takes a ring and return true or false whether or not the ring is clockwise or counter-clockwise. * - * @name booleanClockwise + * @function * @param {Feature|LineString|Array>} line to be evaluated * @returns {boolean} true/false * @example diff --git a/packages/turf-boolean-concave/index.ts b/packages/turf-boolean-concave/index.ts index 25d97e95c..0d4404a7f 100644 --- a/packages/turf-boolean-concave/index.ts +++ b/packages/turf-boolean-concave/index.ts @@ -4,7 +4,7 @@ import { getGeom } from "@turf/invariant"; /** * Takes a polygon and return true or false as to whether it is concave or not. * - * @name booleanConcave + * @function * @param {Feature} polygon to be evaluated * @returns {boolean} true/false * @example diff --git a/packages/turf-boolean-contains/index.ts b/packages/turf-boolean-contains/index.ts index c7397fda8..98e390331 100644 --- a/packages/turf-boolean-contains/index.ts +++ b/packages/turf-boolean-contains/index.ts @@ -19,7 +19,7 @@ import { getGeom } from "@turf/invariant"; * must not intersect the exterior of the primary (geometry a). * Boolean-contains returns the exact opposite result of the `@turf/boolean-within`. * - * @name booleanContains + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @returns {boolean} true/false diff --git a/packages/turf-boolean-crosses/index.ts b/packages/turf-boolean-crosses/index.ts index f706bb179..0b611ef31 100644 --- a/packages/turf-boolean-crosses/index.ts +++ b/packages/turf-boolean-crosses/index.ts @@ -13,7 +13,7 @@ import { point } from "@turf/helpers"; * Boolean-Crosses returns t (TRUE) for only multipoint/polygon, multipoint/linestring, linestring/linestring, linestring/polygon, and linestring/multipolygon comparisons. * Other comparisons are not supported as they are outside the OpenGIS Simple Features spec and may give unexpected results. * - * @name booleanCrosses + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @returns {boolean} true/false diff --git a/packages/turf-boolean-disjoint/index.ts b/packages/turf-boolean-disjoint/index.ts index b682dfda6..60e89c23f 100644 --- a/packages/turf-boolean-disjoint/index.ts +++ b/packages/turf-boolean-disjoint/index.ts @@ -14,7 +14,7 @@ import { polygonToLine } from "@turf/polygon-to-line"; /** * Boolean-disjoint returns (TRUE) if the intersection of the two geometries is an empty set. * - * @name booleanDisjoint + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-boolean-equal/index.ts b/packages/turf-boolean-equal/index.ts index 9e009bfa2..4d44f279e 100644 --- a/packages/turf-boolean-equal/index.ts +++ b/packages/turf-boolean-equal/index.ts @@ -7,7 +7,7 @@ import { getGeom } from "@turf/invariant"; * Determine whether two geometries of the same type have identical X,Y coordinate values. * See http://edndoc.esri.com/arcsde/9.0/general_topics/understand_spatial_relations.htm * - * @name booleanEqual + * @function * @param {Geometry|Feature} feature1 GeoJSON input * @param {Geometry|Feature} feature2 GeoJSON input * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-boolean-intersects/index.ts b/packages/turf-boolean-intersects/index.ts index 32ee289b7..5ba9ba7a0 100644 --- a/packages/turf-boolean-intersects/index.ts +++ b/packages/turf-boolean-intersects/index.ts @@ -5,7 +5,7 @@ import { flattenEach } from "@turf/meta"; /** * Boolean-intersects returns (TRUE) if the intersection of the two geometries is NOT an empty set. * - * @name booleanIntersects + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-boolean-overlap/index.ts b/packages/turf-boolean-overlap/index.ts index fc989ace7..898ae3d7c 100644 --- a/packages/turf-boolean-overlap/index.ts +++ b/packages/turf-boolean-overlap/index.ts @@ -12,7 +12,7 @@ import { geojsonEquality } from "geojson-equality-ts"; * * In other words, it returns true if the two geometries overlap, provided that neither completely contains the other. * - * @name booleanOverlap + * @function * @param {Geometry|Feature} feature1 input * @param {Geometry|Feature} feature2 input * @returns {boolean} true/false diff --git a/packages/turf-boolean-parallel/index.ts b/packages/turf-boolean-parallel/index.ts index ddab0c7da..10dadb900 100644 --- a/packages/turf-boolean-parallel/index.ts +++ b/packages/turf-boolean-parallel/index.ts @@ -7,7 +7,7 @@ import { bearingToAzimuth } from "@turf/helpers"; /** * Boolean-Parallel returns True if each segment of `line1` is parallel to the correspondent segment of `line2` * - * @name booleanParallel + * @function * @param {Geometry|Feature} line1 GeoJSON Feature or Geometry * @param {Geometry|Feature} line2 GeoJSON Feature or Geometry * @returns {boolean} true/false if the lines are parallel diff --git a/packages/turf-boolean-point-in-polygon/index.ts b/packages/turf-boolean-point-in-polygon/index.ts index b114d927c..b383cd9b8 100644 --- a/packages/turf-boolean-point-in-polygon/index.ts +++ b/packages/turf-boolean-point-in-polygon/index.ts @@ -16,7 +16,7 @@ import { getCoord, getGeom } from "@turf/invariant"; * Takes a {@link Point} and a {@link Polygon} or {@link MultiPolygon} and determines if the point * resides inside the polygon. The polygon can be convex or concave. The function accounts for holes. * - * @name booleanPointInPolygon + * @function * @param {Coord} point input point * @param {Feature} polygon input polygon or multipolygon * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-boolean-point-on-line/index.ts b/packages/turf-boolean-point-on-line/index.ts index 3d36c316b..9bfb98e43 100644 --- a/packages/turf-boolean-point-on-line/index.ts +++ b/packages/turf-boolean-point-on-line/index.ts @@ -6,7 +6,7 @@ import { getCoord, getCoords } from "@turf/invariant"; * Returns true if a point is on a line. Accepts a optional parameter to ignore the * start and end vertices of the linestring. * - * @name booleanPointOnLine + * @function * @param {Coord} pt GeoJSON Point * @param {Feature} line GeoJSON LineString * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-boolean-touches/index.ts b/packages/turf-boolean-touches/index.ts index dafc15001..a1f4d7791 100644 --- a/packages/turf-boolean-touches/index.ts +++ b/packages/turf-boolean-touches/index.ts @@ -6,7 +6,8 @@ import { getGeom } from "@turf/invariant"; /** * Boolean-touches true if none of the points common to both geometries * intersect the interiors of both geometries. - * @name booleanTouches + * + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @returns {boolean} true/false diff --git a/packages/turf-boolean-valid/index.ts b/packages/turf-boolean-valid/index.ts index f50488ac9..b61d79f3f 100644 --- a/packages/turf-boolean-valid/index.ts +++ b/packages/turf-boolean-valid/index.ts @@ -9,7 +9,7 @@ import { booleanPointOnLine as isPointOnLine } from "@turf/boolean-point-on-line /** * booleanValid checks if the geometry is a valid according to the OGC Simple Feature Specification. * - * @name booleanValid + * @function * @param {Geometry|Feature} feature GeoJSON Feature or Geometry * @returns {boolean} true/false * @example diff --git a/packages/turf-boolean-within/index.ts b/packages/turf-boolean-within/index.ts index 762195e40..db0bf0b0a 100644 --- a/packages/turf-boolean-within/index.ts +++ b/packages/turf-boolean-within/index.ts @@ -19,7 +19,7 @@ import { getGeom } from "@turf/invariant"; * must not intersect the exterior of the secondary (geometry b). * Boolean-within returns the exact opposite result of the `@turf/boolean-contains`. * - * @name booleanWithin + * @function * @param {Geometry|Feature} feature1 GeoJSON Feature or Geometry * @param {Geometry|Feature} feature2 GeoJSON Feature or Geometry * @returns {boolean} true/false diff --git a/packages/turf-buffer/index.js b/packages/turf-buffer/index.js index 78f897c42..9ab972403 100644 --- a/packages/turf-buffer/index.js +++ b/packages/turf-buffer/index.js @@ -21,7 +21,7 @@ const { BufferOp, GeoJSONReader, GeoJSONWriter } = jsts; * FeatureCollection - i.e., the output collection may have fewer members than * the input, or even be empty. * - * @name buffer + * @function * @param {FeatureCollection|Geometry|Feature} geojson input to be buffered * @param {number} radius distance to draw the buffer (negative values are allowed) * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-center-mean/index.ts b/packages/turf-center-mean/index.ts index c94733c79..3d8814f90 100644 --- a/packages/turf-center-mean/index.ts +++ b/packages/turf-center-mean/index.ts @@ -5,7 +5,7 @@ import { isNumber, point, Id } from "@turf/helpers"; /** * Takes a {@link Feature} or {@link FeatureCollection} and returns the mean center. Can be weighted. * - * @name centerMean + * @function * @param {GeoJSON} geojson GeoJSON to be centered * @param {Object} [options={}] Optional parameters * @param {Object} [options.properties={}] Translate GeoJSON Properties to Point diff --git a/packages/turf-center-median/index.ts b/packages/turf-center-median/index.ts index 9475ee3b6..b0240ece9 100644 --- a/packages/turf-center-median/index.ts +++ b/packages/turf-center-median/index.ts @@ -43,7 +43,7 @@ import { featureEach } from "@turf/meta"; * Statistics for Geographers_, 3rd ed., New York: The Guilford * Press, 2009, 150–151. * - * @name centerMedian + * @function * @param {FeatureCollection} features Any GeoJSON Feature Collection * @param {Object} [options={}] Optional parameters * @param {string} [options.weight] the property name used to weight the center diff --git a/packages/turf-center-of-mass/index.ts b/packages/turf-center-of-mass/index.ts index f24b55d51..819bd5583 100644 --- a/packages/turf-center-of-mass/index.ts +++ b/packages/turf-center-of-mass/index.ts @@ -8,7 +8,7 @@ import { coordEach } from "@turf/meta"; /** * Takes any {@link Feature} or a {@link FeatureCollection} and returns its [center of mass](https://en.wikipedia.org/wiki/Center_of_mass) using this formula: [Centroid of Polygon](https://en.wikipedia.org/wiki/Centroid#Centroid_of_polygon). * - * @name centerOfMass + * @function * @param {GeoJSON} geojson GeoJSON to be centered * @param {Object} [options={}] Optional Parameters * @param {Object} [options.properties={}] Translate Properties to Feature diff --git a/packages/turf-center/index.ts b/packages/turf-center/index.ts index 5a599b35b..f23c8697c 100644 --- a/packages/turf-center/index.ts +++ b/packages/turf-center/index.ts @@ -5,7 +5,7 @@ import { point, Id, AllGeoJSON } from "@turf/helpers"; /** * Takes a {@link Feature} or {@link FeatureCollection} and returns the absolute center point of all features. * - * @name center + * @function * @param {GeoJSON} geojson GeoJSON to be centered * @param {Object} [options={}] Optional parameters * @param {Object} [options.properties={}] Translate GeoJSON Properties to Point diff --git a/packages/turf-centroid/index.ts b/packages/turf-centroid/index.ts index 7a6ac39cf..0a662e806 100644 --- a/packages/turf-centroid/index.ts +++ b/packages/turf-centroid/index.ts @@ -5,7 +5,7 @@ import { coordEach } from "@turf/meta"; /** * Computes the centroid as the mean of all vertices within the object. * - * @name centroid + * @function * @param {GeoJSON} geojson GeoJSON to be centered * @param {Object} [options={}] Optional Parameters * @param {Object} [options.properties={}] an Object that is used as the {@link Feature}'s properties diff --git a/packages/turf-circle/index.ts b/packages/turf-circle/index.ts index dd4d8d57f..e9e0410e5 100644 --- a/packages/turf-circle/index.ts +++ b/packages/turf-circle/index.ts @@ -5,7 +5,7 @@ import { polygon, Units } from "@turf/helpers"; /** * Takes a {@link Point} and calculates the circle polygon given a radius in degrees, radians, miles, or kilometers; and steps for precision. * - * @name circle + * @function * @param {Feature|number[]} center center point * @param {number} radius radius of the circle * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-clean-coords/index.ts b/packages/turf-clean-coords/index.ts index a1ff53c02..3be8ba3ef 100644 --- a/packages/turf-clean-coords/index.ts +++ b/packages/turf-clean-coords/index.ts @@ -7,7 +7,7 @@ import { getCoords, getType } from "@turf/invariant"; /** * Removes redundant coordinates from any GeoJSON Geometry. * - * @name cleanCoords + * @function * @param {Geometry|Feature} geojson Feature or Geometry * @param {Object} [options={}] Optional parameters * @param {boolean} [options.mutate=false] allows GeoJSON input to be mutated diff --git a/packages/turf-clone/index.ts b/packages/turf-clone/index.ts index 206ec7318..72aa3db1c 100644 --- a/packages/turf-clone/index.ts +++ b/packages/turf-clone/index.ts @@ -5,7 +5,7 @@ import { AllGeoJSON } from "@turf/helpers"; * Returns a cloned copy of the passed GeoJSON Object, including possible 'Foreign Members'. * ~3-5x faster than the common JSON.parse + JSON.stringify combo method. * - * @name clone + * @function * @param {GeoJSON} geojson GeoJSON Object * @returns {GeoJSON} cloned GeoJSON Object * @example diff --git a/packages/turf-clusters-dbscan/README.md b/packages/turf-clusters-dbscan/README.md index 2b4c8d107..0b3c12791 100644 --- a/packages/turf-clusters-dbscan/README.md +++ b/packages/turf-clusters-dbscan/README.md @@ -2,19 +2,38 @@ +## Dbscan + +Point classification within the cluster. + +Type: (`"core"` | `"edge"` | `"noise"`) + +## DbscanProps + +**Extends GeoJsonProperties** + +Properties assigned to each clustered point. + +Type: [object][1] + +### Properties + +* `dbscan` **[Dbscan][2]?** type of point it has been classified as +* `cluster` **[number][3]?** associated clusterId + ## clustersDbscan -Takes a set of [points][1] and partition them into clusters according to [https://en.wikipedia.org/wiki/DBSCAN][2] data clustering algorithm. +Takes a set of [points][4] and partition them into clusters according to [DBSCAN's][5] data clustering algorithm. ### Parameters -* `points` **[FeatureCollection][3]<[Point][1]>** to be clustered -* `maxDistance` **[number][4]** Maximum Distance between any point of the cluster to generate the clusters (kilometers by default, see options) -* `options` **[Object][5]** Optional parameters (optional, default `{}`) +* `points` **[FeatureCollection][6]<[Point][4]>** to be clustered +* `maxDistance` **[number][3]** Maximum Distance between any point of the cluster to generate the clusters (kilometers by default, see options) +* `options` **[Object][1]** Optional parameters (optional, default `{}`) - * `options.units` **[string][6]** in which `maxDistance` is expressed, can be degrees, radians, miles, or kilometers (optional, default `"kilometers"`) - * `options.mutate` **[boolean][7]** Allows GeoJSON input to be mutated (optional, default `false`) - * `options.minPoints` **[number][4]** Minimum number of points to generate a single cluster, + * `options.units` **[string][7]** in which `maxDistance` is expressed, can be degrees, radians, miles, or kilometers (optional, default `"kilometers"`) + * `options.mutate` **[boolean][8]** Allows GeoJSON input to be mutated (optional, default `false`) + * `options.minPoints` **[number][3]** Minimum number of points to generate a single cluster, points which do not meet this requirement will be classified as an 'edge' or 'noise'. (optional, default `3`) ### Examples @@ -29,22 +48,26 @@ var clustered = turf.clustersDbscan(points, maxDistance); var addToMap = [clustered]; ``` -Returns **[FeatureCollection][3]<[Point][1]>** Clustered Points with an additional two properties associated to each Feature:* {number} cluster - the associated clusterId +Returns **[FeatureCollection][6]<[Point][4], [DbscanProps][9]>** Clustered Points with an additional two properties associated to each Feature:* {number} cluster - the associated clusterId * {string} dbscan - type of point it has been classified as ('core'|'edge'|'noise') -[1]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: #dbscan + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[2]: DBSCAN's +[4]: https://tools.ietf.org/html/rfc7946#section-3.1.2 -[3]: https://tools.ietf.org/html/rfc7946#section-3.3 +[5]: https://en.wikipedia.org/wiki/DBSCAN -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[6]: https://tools.ietf.org/html/rfc7946#section-3.3 -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[9]: #dbscanprops diff --git a/packages/turf-clusters-dbscan/index.ts b/packages/turf-clusters-dbscan/index.ts index fa89f4e8b..ef87d5ec7 100644 --- a/packages/turf-clusters-dbscan/index.ts +++ b/packages/turf-clusters-dbscan/index.ts @@ -4,7 +4,21 @@ import { distance } from "@turf/distance"; import { degreesToRadians, lengthToDegrees, Units } from "@turf/helpers"; import { rbush as RBush } from "./lib/rbush-export.js"; +/** + * Point classification within the cluster. + * + * @typedef {"core" | "edge" | "noise"} Dbscan + */ type Dbscan = "core" | "edge" | "noise"; + +/** + * Properties assigned to each clustered point. + * + * @extends GeoJsonProperties + * @typedef {object} DbscanProps + * @property {Dbscan} [dbscan] type of point it has been classified as + * @property {number} [cluster] associated clusterId + */ type DbscanProps = GeoJsonProperties & { dbscan?: Dbscan; cluster?: number; @@ -20,9 +34,9 @@ type IndexedPoint = { }; /** - * Takes a set of {@link Point|points} and partition them into clusters according to {@link DBSCAN's|https://en.wikipedia.org/wiki/DBSCAN} data clustering algorithm. + * Takes a set of {@link Point|points} and partition them into clusters according to {@link https://en.wikipedia.org/wiki/DBSCAN|DBSCAN's} data clustering algorithm. * - * @name clustersDbscan + * @function * @param {FeatureCollection} points to be clustered * @param {number} maxDistance Maximum Distance between any point of the cluster to generate the clusters (kilometers by default, see options) * @param {Object} [options={}] Optional parameters @@ -30,7 +44,7 @@ type IndexedPoint = { * @param {boolean} [options.mutate=false] Allows GeoJSON input to be mutated * @param {number} [options.minPoints=3] Minimum number of points to generate a single cluster, * points which do not meet this requirement will be classified as an 'edge' or 'noise'. - * @returns {FeatureCollection} Clustered Points with an additional two properties associated to each Feature: + * @returns {FeatureCollection} Clustered Points with an additional two properties associated to each Feature: * - {number} cluster - the associated clusterId * - {string} dbscan - type of point it has been classified as ('core'|'edge'|'noise') * @example diff --git a/packages/turf-clusters-kmeans/index.ts b/packages/turf-clusters-kmeans/index.ts index fdc85be83..df7e44141 100644 --- a/packages/turf-clusters-kmeans/index.ts +++ b/packages/turf-clusters-kmeans/index.ts @@ -12,7 +12,7 @@ type KmeansProps = GeoJsonProperties & { * Takes a set of {@link Point|points} and partition them into clusters using the k-mean . * It uses the [k-means algorithm](https://en.wikipedia.org/wiki/K-means_clustering) * - * @name clustersKmeans + * @function * @param {FeatureCollection} points to be clustered * @param {Object} [options={}] Optional parameters * @param {number} [options.numberOfClusters=Math.sqrt(numberOfPoints/2)] numberOfClusters that will be generated diff --git a/packages/turf-clusters/README.md b/packages/turf-clusters/README.md index 51531ab0f..0183e7a6a 100644 --- a/packages/turf-clusters/README.md +++ b/packages/turf-clusters/README.md @@ -60,7 +60,7 @@ clusterEach * `geojson` **[FeatureCollection][1]** GeoJSON Features * `property` **([string][4] | [number][3])** GeoJSON property key/value used to create clusters -* `callback` **[Function][2]** a method that takes (cluster, clusterValue, currentIndex) +* `callback` **[clusterEachCallback][5]** a method that takes (cluster, clusterValue, currentIndex) ### Examples @@ -126,6 +126,8 @@ Type: [Function][2] * `currentIndex` **[number][3]?** The index of the current element being processed in the array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. +Returns **void** + ## clusterReduce Reduce clusters in GeoJSON Features, similar to Array.reduce() @@ -134,7 +136,7 @@ Reduce clusters in GeoJSON Features, similar to Array.reduce() * `geojson` **[FeatureCollection][1]** GeoJSON Features * `property` **([string][4] | [number][3])** GeoJSON property key/value used to create clusters -* `callback` **[Function][2]** a method that takes (previousValue, cluster, clusterValue, currentIndex) +* `callback` **[clusterReduceCallback][6]** a method that takes (previousValue, cluster, clusterValue, currentIndex) * `initialValue` **any?** Value to use as the first argument to the first call of the callback. ### Examples @@ -182,6 +184,10 @@ Returns **any** The value that results from the reduction. [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[5]: #clustereachcallback + +[6]: #clusterreducecallback + --- diff --git a/packages/turf-clusters/index.ts b/packages/turf-clusters/index.ts index 0d72b2abc..e1bd22343 100644 --- a/packages/turf-clusters/index.ts +++ b/packages/turf-clusters/index.ts @@ -10,7 +10,7 @@ import { featureCollection } from "@turf/helpers"; /** * Get Cluster * - * @name getCluster + * @function * @param {FeatureCollection} geojson GeoJSON Features * @param {*} filter Filter used on GeoJSON properties to get Cluster * @returns {FeatureCollection} Single Cluster filtered by GeoJSON Properties @@ -60,7 +60,7 @@ function getCluster< * * @callback clusterEachCallback * @param {FeatureCollection} [cluster] The current cluster being processed. - * @param {*} [clusterValue] Value used to create cluster being processed. + * @param {any} [clusterValue] Value used to create cluster being processed. * @param {number} [currentIndex] The index of the current element being processed in the array.Starts at index 0 * @returns {void} */ @@ -68,10 +68,10 @@ function getCluster< /** * clusterEach * - * @name clusterEach + * @function * @param {FeatureCollection} geojson GeoJSON Features * @param {string|number} property GeoJSON property key/value used to create clusters - * @param {Function} callback a method that takes (cluster, clusterValue, currentIndex) + * @param {clusterEachCallback} callback a method that takes (cluster, clusterValue, currentIndex) * @returns {void} * @example * var geojson = turf.featureCollection([ @@ -158,17 +158,18 @@ function clusterEach< * @param {*} [clusterValue] Value used to create cluster being processed. * @param {number} [currentIndex] The index of the current element being processed in the * array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. + * @returns {void} */ /** * Reduce clusters in GeoJSON Features, similar to Array.reduce() * - * @name clusterReduce + * @function * @param {FeatureCollection} geojson GeoJSON Features * @param {string|number} property GeoJSON property key/value used to create clusters - * @param {Function} callback a method that takes (previousValue, cluster, clusterValue, currentIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @param {clusterReduceCallback} callback a method that takes (previousValue, cluster, clusterValue, currentIndex) + * @param {any} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {any} The value that results from the reduction. * @example * var geojson = turf.featureCollection([ * turf.point([0, 0]), diff --git a/packages/turf-collect/index.ts b/packages/turf-collect/index.ts index bde4e7c06..2811a522a 100644 --- a/packages/turf-collect/index.ts +++ b/packages/turf-collect/index.ts @@ -18,7 +18,7 @@ interface Entry { * `inProperty` values from those points, and adds them as an array to `outProperty` * on the polygon. * - * @name collect + * @function * @param {FeatureCollection} polygons polygons with values on which to aggregate * @param {FeatureCollection} points points to be aggregated * @param {string} inProperty property to be nested from diff --git a/packages/turf-combine/index.ts b/packages/turf-combine/index.ts index e3e72a4a4..21650bff5 100644 --- a/packages/turf-combine/index.ts +++ b/packages/turf-combine/index.ts @@ -15,7 +15,7 @@ import { featureEach } from "@turf/meta"; * Combines a {@link FeatureCollection} of {@link Point}, {@link LineString}, or {@link Polygon} features * into {@link MultiPoint}, {@link MultiLineString}, or {@link MultiPolygon} features. * - * @name combine + * @function * @param {FeatureCollection} fc a FeatureCollection of any type * @returns {FeatureCollection} a FeatureCollection of corresponding type to input * @example diff --git a/packages/turf-concave/index.ts b/packages/turf-concave/index.ts index d0a87b5c5..fbfa28e92 100644 --- a/packages/turf-concave/index.ts +++ b/packages/turf-concave/index.ts @@ -16,7 +16,7 @@ import { dissolve } from "./lib/turf-dissolve.js"; * Takes a set of {@link Point|points} and returns a concave hull Polygon or MultiPolygon. * Internally, this uses [turf-tin](https://github.com/Turfjs/turf-tin) to generate geometries. * - * @name concave + * @function * @param {FeatureCollection} points input points * @param {Object} [options={}] Optional parameters * @param {number} [options.maxEdge=Infinity] the length (in 'units') of an edge necessary for part of the diff --git a/packages/turf-convex/index.ts b/packages/turf-convex/index.ts index d89cc7c4d..d7969ec59 100644 --- a/packages/turf-convex/index.ts +++ b/packages/turf-convex/index.ts @@ -10,7 +10,7 @@ import concaveman from "concaveman"; * the [convex-hull](https://github.com/mikolalysenko/convex-hull) module that implements a * [monotone chain hull](http://en.wikibooks.org/wiki/Algorithm_Implementation/Geometry/Convex_hull/Monotone_chain). * - * @name convex + * @function * @param {GeoJSON} geojson input Feature or FeatureCollection * @param {Object} [options={}] Optional parameters * @param {number} [options.concavity=Infinity] 1 - thin shape. Infinity - convex hull. diff --git a/packages/turf-destination/index.ts b/packages/turf-destination/index.ts index ab6d110e1..a5352994c 100644 --- a/packages/turf-destination/index.ts +++ b/packages/turf-destination/index.ts @@ -16,7 +16,7 @@ import { getCoord } from "@turf/invariant"; * degrees, radians, miles, or kilometers; and bearing in degrees. * This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature. * - * @name destination + * @function * @param {Coord} origin starting point * @param {number} distance distance from the origin point * @param {number} bearing ranging from -180 to 180 diff --git a/packages/turf-difference/index.ts b/packages/turf-difference/index.ts index 8629db4b0..51eabd77a 100644 --- a/packages/turf-difference/index.ts +++ b/packages/turf-difference/index.ts @@ -6,7 +6,7 @@ import { geomEach } from "@turf/meta"; /** * Finds the difference between multiple {@link Polygon|polygons} by clipping the subsequent polygon from the first. * - * @name difference + * @function * @param {FeatureCollection} features input Polygon features * @returns {Feature|null} a Polygon or MultiPolygon feature showing the area of `polygon1` excluding the area of `polygon2` (if empty returns `null`) * @example diff --git a/packages/turf-directional-mean/index.ts b/packages/turf-directional-mean/index.ts index bb21d837b..ab92794e3 100644 --- a/packages/turf-directional-mean/index.ts +++ b/packages/turf-directional-mean/index.ts @@ -36,7 +36,8 @@ interface DirectionalMeanLine extends Feature { * This module calculate the average angle of a set of lines, measuring the trend of it. * It can be used in both project coordinate system and geography coordinate system. * It can handle segments of line or the whole line. - * @name directionalMean + * + * @function * @param {FeatureCollection} lines * @param {object} [options={}] * @param {boolean} [options.planar=true] whether the spatial reference system is projected or geographical. diff --git a/packages/turf-dissolve/README.md b/packages/turf-dissolve/README.md index 803ecf10d..e5cdc706f 100644 --- a/packages/turf-dissolve/README.md +++ b/packages/turf-dissolve/README.md @@ -4,15 +4,16 @@ ## dissolve -Dissolves a FeatureCollection of [polygon][1] features, filtered by an optional property name:value. -Note that [mulitpolygon][2] features within the collection are not supported +Dissolves a FeatureCollection of [Polygon][1] features, filtered by an optional property name:value. +Note that [MultiPolygon][2] features within the collection are not supported ### Parameters -* `featureCollection` **[FeatureCollection][3]<[Polygon][4]>** input feature collection to be dissolved -* `options` **[Object][5]** Optional parameters (optional, default `{}`) +* `fc` **[FeatureCollection][3]<[Polygon][1]>** +* `options` **[Object][4]** Optional parameters (optional, default `{}`) - * `options.propertyName` **[string][6]?** features with the same `propertyName` value will be dissolved. + * `options.propertyName` **[string][5]?** features with the same `propertyName` value will be dissolved. +* `featureCollection` **[FeatureCollection][3]<[Polygon][1]>** input feature collection to be dissolved ### Examples @@ -29,19 +30,17 @@ var dissolved = turf.dissolve(features, {propertyName: 'combine'}); var addToMap = [features, dissolved] ``` -Returns **[FeatureCollection][3]<[Polygon][4]>** a FeatureCollection containing the dissolved polygons +Returns **[FeatureCollection][3]<[Polygon][1]>** a FeatureCollection containing the dissolved polygons -[1]: polygon +[1]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[2]: mulitpolygon +[2]: https://tools.ietf.org/html/rfc7946#section-3.1.7 [3]: https://tools.ietf.org/html/rfc7946#section-3.3 -[4]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object - -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/packages/turf-dissolve/index.ts b/packages/turf-dissolve/index.ts index fd5a5eb2d..0066b34f9 100644 --- a/packages/turf-dissolve/index.ts +++ b/packages/turf-dissolve/index.ts @@ -6,10 +6,10 @@ import { flatten } from "@turf/flatten"; import polygonClipping, { Geom } from "polygon-clipping"; /** - * Dissolves a FeatureCollection of {@link polygon} features, filtered by an optional property name:value. - * Note that {@link mulitpolygon} features within the collection are not supported + * Dissolves a FeatureCollection of {@link Polygon} features, filtered by an optional property name:value. + * Note that {@link MultiPolygon} features within the collection are not supported * - * @name dissolve + * @function * @param {FeatureCollection} featureCollection input feature collection to be dissolved * @param {Object} [options={}] Optional parameters * @param {string} [options.propertyName] features with the same `propertyName` value will be dissolved. diff --git a/packages/turf-distance-weight/index.ts b/packages/turf-distance-weight/index.ts index cdac777c7..bb966dd2b 100644 --- a/packages/turf-distance-weight/index.ts +++ b/packages/turf-distance-weight/index.ts @@ -5,6 +5,8 @@ import { featureEach } from "@turf/meta"; /** * calcualte the Minkowski p-norm distance between two features. + * + * @function * @param feature1 point feature * @param feature2 point feature * @param p p-norm 1=} fc FeatureCollection. * @param {Object} [options] option object. * @param {number} [options.threshold=10000] If the distance between neighbor and diff --git a/packages/turf-distance/index.ts b/packages/turf-distance/index.ts index 3c19e6a2f..b9f977118 100644 --- a/packages/turf-distance/index.ts +++ b/packages/turf-distance/index.ts @@ -8,7 +8,7 @@ import { radiansToLength, degreesToRadians, Coord, Units } from "@turf/helpers"; * Calculates the distance between two {@link Coord|coordinates} in degrees, radians, miles, or kilometers. * This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature. * - * @name distance + * @function * @param {Coord} from origin coordinate * @param {Coord} to destination coordinate * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-envelope/index.ts b/packages/turf-envelope/index.ts index 1db373e12..d8536289d 100644 --- a/packages/turf-envelope/index.ts +++ b/packages/turf-envelope/index.ts @@ -6,7 +6,7 @@ import { bboxPolygon } from "@turf/bbox-polygon"; /** * Takes any number of features and returns a rectangular {@link Polygon} that encompasses all vertices. * - * @name envelope + * @function * @param {GeoJSON} geojson input features * @returns {Feature} a rectangular Polygon feature that encompasses all vertices * @example diff --git a/packages/turf-explode/index.ts b/packages/turf-explode/index.ts index 2ca866bb6..407593269 100644 --- a/packages/turf-explode/index.ts +++ b/packages/turf-explode/index.ts @@ -6,7 +6,7 @@ import type { Feature, FeatureCollection, Point } from "geojson"; /** * Takes a feature or set of features and returns all positions as {@link Point|points}. * - * @name explode + * @function * @param {GeoJSON} geojson input features * @returns {FeatureCollection} points representing the exploded input features * @throws {Error} if it encounters an unknown geometry type diff --git a/packages/turf-flatten/index.ts b/packages/turf-flatten/index.ts index 3ed12e7aa..d2af980a4 100644 --- a/packages/turf-flatten/index.ts +++ b/packages/turf-flatten/index.ts @@ -15,7 +15,7 @@ import type { /** * Flattens any {@link GeoJSON} to a {@link FeatureCollection} inspired by [geojson-flatten](https://github.com/tmcw/geojson-flatten). * - * @name flatten + * @function * @param {GeoJSON} geojson any valid GeoJSON Object * @returns {FeatureCollection} all Multi-Geometries are flattened into single Features * @example diff --git a/packages/turf-flip/index.ts b/packages/turf-flip/index.ts index a5e84bf35..ba53101a2 100644 --- a/packages/turf-flip/index.ts +++ b/packages/turf-flip/index.ts @@ -5,7 +5,7 @@ import { clone } from "@turf/clone"; /** * Takes input features and flips all of their coordinates from `[x, y]` to `[y, x]`. * - * @name flip + * @function * @param {GeoJSON} geojson input features * @param {Object} [options={}] Optional parameters * @param {boolean} [options.mutate=false] allows GeoJSON input to be mutated (significant performance increase if true) diff --git a/packages/turf-geojson-rbush/index.js b/packages/turf-geojson-rbush/index.js index 55945bbf2..bae88b283 100644 --- a/packages/turf-geojson-rbush/index.js +++ b/packages/turf-geojson-rbush/index.js @@ -10,7 +10,7 @@ import { bbox as turfBBox } from "@turf/bbox"; /** * GeoJSON implementation of [RBush](https://github.com/mourner/rbush#rbush) spatial index. * - * @name rbush + * @function rbush * @param {number} [maxEntries=9] defines the maximum number of entries in a tree node. 9 (used by default) is a * reasonable choice for most applications. Higher value means faster insertion and slower search, and vice versa. * @returns {RBush} GeoJSON RBush diff --git a/packages/turf-great-circle/index.js b/packages/turf-great-circle/index.js index 8cbbeaeae..bd4ee79d8 100644 --- a/packages/turf-great-circle/index.js +++ b/packages/turf-great-circle/index.js @@ -6,7 +6,7 @@ import { GreatCircle } from "./lib/arc.js"; * If the `start` and `end` points span the antimeridian, the resulting feature will * be split into a `MultiLineString`. * - * @name greatCircle + * @function * @param {Coord} start source point feature * @param {Coord} end destination point feature * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-helpers/README.md b/packages/turf-helpers/README.md index a232426ad..040155153 100644 --- a/packages/turf-helpers/README.md +++ b/packages/turf-helpers/README.md @@ -4,38 +4,75 @@ ## helpers -### earthRadius +## Units -The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The [mean radius][1] was selected because it is [recommended ][2] by the Haversine formula (used by turf/distance) to reduce error. +Linear measurement units. -Type: [number][3] +Type: (`"meters"` | `"metres"` | `"millimeters"` | `"millimetres"` | `"centimeters"` | `"centimetres"` | `"kilometers"` | `"kilometres"` | `"miles"` | `"nauticalmiles"` | `"inches"` | `"yards"` | `"feet"` | `"radians"` | `"degrees"`) -### factors +## AreaUnits + +Area measurement units. + +Type: (Exclude<[Units][1], (`"radians"` | `"degrees"`)> | `"acres"` | `"hectares"`) + +## Grid + +Grid types. + +Type: (`"point"` | `"square"` | `"hex"` | `"triangle"`) + +## Corners + +Shorthand corner identifiers. + +Type: (`"sw"` | `"se"` | `"nw"` | `"ne"` | `"center"` | `"centroid"`) + +## Lines + +Geometries made up of lines i.e. lines and polygons. + +Type: ([LineString][2] | [MultiLineString][3] | [Polygon][4] | [MultiPolygon][5]) + +## AllGeoJSON + +Convenience type for all possible GeoJSON. + +Type: ([Feature][6] | [FeatureCollection][7] | [Geometry][8] | [GeometryCollection][9]) + +## earthRadius + +The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The [mean radius][10] was selected because it is [recommended ][11] by the Haversine formula (used by turf/distance) to reduce error. + +Type: [number][12] + +## factors Unit of measurement factors based on earthRadius. Keys are the name of the unit, values are the number of that unit in a single radian -Type: [Object][4] +Type: Record<[Units][1], [number][12]> -### areaFactors +## areaFactors Area of measurement factors based on 1 square meter. -Type: [Object][4] +Type: Record<[AreaUnits][13], [number][12]> ## feature -Wraps a GeoJSON [Geometry][5] in a GeoJSON [Feature][6]. +Wraps a GeoJSON [Geometry][8] in a GeoJSON [Feature][6]. ### Parameters -* `geometry` **[Geometry][5]** input geometry -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `geom` **(G | null)** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature +* `geometry` **[GeometryObject][8]** input geometry ### Examples @@ -50,18 +87,19 @@ var feature = turf.feature(geometry); //=feature ``` -Returns **[Feature][6]** a GeoJSON Feature +Returns **[Feature][6]<[GeometryObject][8], [GeoJsonProperties][6]>** a GeoJSON Feature ## geometry -Creates a GeoJSON [Geometry][5] from a Geometry string type & coordinates. +Creates a GeoJSON [Geometry][8] from a Geometry string type & coordinates. For GeometryCollection type use `helpers.geometryCollection` ### Parameters -* `type` **[string][8]** Geometry Type -* `coordinates` **[Array][7]\** Coordinates -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `type` **(`"Point"` | `"LineString"` | `"Polygon"` | `"MultiPoint"` | `"MultiLineString"` | `"MultiPolygon"`)** Geometry Type +* `coordinates` **[Array][16]\** Coordinates +* `_options` **Record<[string][17], never>** (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) ### Examples @@ -72,20 +110,20 @@ var geometry = turf.geometry(type, coordinates); // => geometry ``` -Returns **[Geometry][5]** a GeoJSON Geometry +Returns **[Geometry][8]** a GeoJSON Geometry ## point -Creates a [Point][9] [Feature][6] from a Position. +Creates a [Point][18] [Feature][6] from a Position. ### Parameters -* `coordinates` **[Array][7]<[number][3]>** longitude, latitude position (each in decimal degrees) -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Position][19]** longitude, latitude position (each in decimal degrees) +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -95,21 +133,21 @@ var point = turf.point([-75.343, 39.984]); //=point ``` -Returns **[Feature][6]<[Point][9]>** a Point feature +Returns **[Feature][6]<[Point][18], [GeoJsonProperties][6]>** a Point feature ## points -Creates a [Point][9] [FeatureCollection][10] from an Array of Point coordinates. +Creates a [Point][18] [FeatureCollection][7] from an Array of Point coordinates. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Points -* `properties` **[Object][4]** Translate these properties to each Feature (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Position][19]>** an array of Points +* `properties` **[GeoJsonProperties][6]** Translate these properties to each Feature (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the FeatureCollection - * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection + * `options.id` **Id?** Identifier associated with the FeatureCollection ### Examples @@ -123,20 +161,20 @@ var points = turf.points([ //=points ``` -Returns **[FeatureCollection][10]<[Point][9]>** Point Feature +Returns **[FeatureCollection][7]<[Point][18]>** Point Feature ## polygon -Creates a [Polygon][11] [Feature][6] from an Array of LinearRings. +Creates a [Polygon][4] [Feature][6] from an Array of LinearRings. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LinearRings -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Array][16]<[Position][19]>>** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -146,20 +184,20 @@ var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], //=polygon ``` -Returns **[Feature][6]<[Polygon][11]>** Polygon Feature +Returns **[Feature][6]<[Polygon][4], [GeoJsonProperties][6]>** Polygon Feature ## polygons -Creates a [Polygon][11] [FeatureCollection][10] from an Array of Polygon coordinates. +Creates a [Polygon][4] [FeatureCollection][7] from an Array of Polygon coordinates. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[Array][7]<[number][3]>>>>** an array of Polygon coordinates -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Array][16]<[Array][16]<[Position][19]>>>** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the FeatureCollection ### Examples @@ -172,20 +210,20 @@ var polygons = turf.polygons([ //=polygons ``` -Returns **[FeatureCollection][10]<[Polygon][11]>** Polygon FeatureCollection +Returns **[FeatureCollection][7]<[Polygon][4], [GeoJsonProperties][6]>** Polygon FeatureCollection ## lineString -Creates a [LineString][12] [Feature][6] from an Array of Positions. +Creates a [LineString][2] [Feature][6] from an Array of Positions. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Positions -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Position][19]>** an array of Positions +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -197,21 +235,21 @@ var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], //=linestring2 ``` -Returns **[Feature][6]<[LineString][12]>** LineString Feature +Returns **[Feature][6]<[LineString][2], [GeoJsonProperties][6]>** LineString Feature ## lineStrings -Creates a [LineString][12] [FeatureCollection][10] from an Array of LineString coordinates. +Creates a [LineString][2] [FeatureCollection][7] from an Array of LineString coordinates. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LinearRings -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Array][16]<[Position][19]>>** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the FeatureCollection - * `options.id` **([string][8] | [number][3])?** Identifier associated with the FeatureCollection + * `options.id` **Id?** Identifier associated with the FeatureCollection ### Examples @@ -224,19 +262,19 @@ var linestrings = turf.lineStrings([ //=linestrings ``` -Returns **[FeatureCollection][10]<[LineString][12]>** LineString FeatureCollection +Returns **[FeatureCollection][7]<[LineString][2], [GeoJsonProperties][6]>** LineString FeatureCollection ## featureCollection -Takes one or more [Features][6] and creates a [FeatureCollection][10]. +Takes one or more [Features][6] and creates a [FeatureCollection][7]. ### Parameters -* `features` **[Array][7]<[Feature][6]>** input features -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `features` **[Array][16]<[Feature][6]<[GeometryObject][8], [GeoJsonProperties][6]>>** input features +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -254,21 +292,21 @@ var collection = turf.featureCollection([ //=collection ``` -Returns **[FeatureCollection][10]** FeatureCollection of Features +Returns **[FeatureCollection][7]<[GeometryObject][8], [GeoJsonProperties][6]>** FeatureCollection of Features ## multiLineString -Creates a [Feature\][13] based on a +Creates a [Feature][6]<[MultiLineString][3]> based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[number][3]>>>** an array of LineStrings -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Array][16]<[Position][19]>>** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -278,23 +316,23 @@ var multiLine = turf.multiLineString([[[0,0],[10,10]]]); //=multiLine ``` -* Throws **[Error][14]** if no coordinates are passed +* Throws **[Error][20]** if no coordinates are passed -Returns **[Feature][6]<[MultiLineString][15]>** a MultiLineString feature +Returns **[Feature][6]<[MultiLineString][3], [GeoJsonProperties][6]>** a MultiLineString feature ## multiPoint -Creates a [Feature\][16] based on a +Creates a [Feature][6]<[MultiPoint][21]> based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[number][3]>>** an array of Positions -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Position][19]>** an array of Positions +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -304,23 +342,23 @@ var multiPt = turf.multiPoint([[0,0],[10,10]]); //=multiPt ``` -* Throws **[Error][14]** if no coordinates are passed +* Throws **[Error][20]** if no coordinates are passed -Returns **[Feature][6]<[MultiPoint][17]>** a MultiPoint feature +Returns **[Feature][6]<[MultiPoint][21], [GeoJsonProperties][6]>** a MultiPoint feature ## multiPolygon -Creates a [Feature\][18] based on a +Creates a [Feature][6]<[MultiPolygon][5]> based on a coordinate array. Properties can be added optionally. ### Parameters -* `coordinates` **[Array][7]<[Array][7]<[Array][7]<[Array][7]<[number][3]>>>>** an array of Polygons -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `coordinates` **[Array][16]<[Array][16]<[Array][16]<[Position][19]>>>** +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -330,23 +368,23 @@ var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]); //=multiPoly ``` -* Throws **[Error][14]** if no coordinates are passed +* Throws **[Error][20]** if no coordinates are passed -Returns **[Feature][6]<[MultiPolygon][19]>** a multipolygon feature +Returns **[Feature][6]<[MultiPolygon][5], [GeoJsonProperties][6]>** a multipolygon feature ## geometryCollection -Creates a [Feature\][20] based on a +Creates a Feature based on a coordinate array. Properties can be added optionally. ### Parameters -* `geometries` **[Array][7]<[Geometry][5]>** an array of GeoJSON Geometries -* `properties` **[Object][4]** an Object of key-value pairs to add as properties (optional, default `{}`) -* `options` **[Object][4]** Optional Parameters (optional, default `{}`) +* `geometries` **[Array][16]<([Point][18] | [LineString][2] | [Polygon][4] | [MultiPoint][21] | [MultiLineString][3] | [MultiPolygon][5])>** an array of GeoJSON Geometries +* `properties` **[GeoJsonProperties][6]** an Object of key-value pairs to add as properties (optional, default `{}`) +* `options` **[Object][14]** Optional Parameters (optional, default `{}`) - * `options.bbox` **[Array][7]<[number][3]>?** Bounding Box Array \[west, south, east, north] associated with the Feature - * `options.id` **([string][8] | [number][3])?** Identifier associated with the Feature + * `options.bbox` **[BBox][15]?** Bounding Box Array \[west, south, east, north] associated with the Feature + * `options.id` **Id?** Identifier associated with the Feature ### Examples @@ -358,7 +396,7 @@ var collection = turf.geometryCollection([pt, line]); // => collection ``` -Returns **[Feature][6]<[GeometryCollection][21]>** a GeoJSON GeometryCollection Feature +Returns **[Feature][6]<[GeometryCollection][9], [GeoJsonProperties][6]>** a GeoJSON GeometryCollection Feature ## round @@ -366,8 +404,8 @@ Round number to precision ### Parameters -* `num` **[number][3]** Number -* `precision` **[number][3]** Precision (optional, default `0`) +* `num` **[number][12]** Number +* `precision` **[number][12]** Precision (optional, default `0`) ### Examples @@ -379,7 +417,7 @@ turf.round(120.4321, 2) //=120.43 ``` -Returns **[number][3]** rounded number +Returns **[number][12]** rounded number ## radiansToLength @@ -388,11 +426,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `radians` **[number][3]** in radians across the sphere -* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, +* `radians` **[number][12]** in radians across the sphere +* `units` **[Units][1]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][3]** distance +Returns **[number][12]** distance ## lengthToRadians @@ -401,11 +439,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `distance` **[number][3]** in real units -* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, +* `distance` **[number][12]** in real units +* `units` **[Units][1]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][3]** radians +Returns **[number][12]** radians ## lengthToDegrees @@ -414,11 +452,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, k ### Parameters -* `distance` **[number][3]** in real units -* `units` **[string][8]** can be degrees, radians, miles, inches, yards, metres, +* `distance` **[number][12]** in real units +* `units` **[Units][1]** can be degrees, radians, miles, inches, yards, metres, meters, kilometres, kilometers. (optional, default `"kilometers"`) -Returns **[number][3]** degrees +Returns **[number][12]** degrees ## bearingToAzimuth @@ -427,9 +465,9 @@ and returns an angle between 0-360 degrees (positive clockwise), 0 being the nor ### Parameters -* `bearing` **[number][3]** angle, between -180 and +180 degrees +* `bearing` **[number][12]** angle, between -180 and +180 degrees -Returns **[number][3]** angle between 0 and 360 degrees +Returns **[number][12]** angle between 0 and 360 degrees ## azimuthToBearing @@ -438,9 +476,9 @@ and returns an angle between -180 and +180 degrees (positive clockwise), 0 being ### Parameters -* `angle` **[number][3]** between 0 and 360 degrees +* `angle` **[number][12]** between 0 and 360 degrees -Returns **[number][3]** bearing between -180 and +180 degrees +Returns **[number][12]** bearing between -180 and +180 degrees ## radiansToDegrees @@ -448,9 +486,9 @@ Converts an angle in radians to degrees ### Parameters -* `radians` **[number][3]** angle in radians +* `radians` **[number][12]** angle in radians -Returns **[number][3]** degrees between 0 and 360 degrees +Returns **[number][12]** degrees between 0 and 360 degrees ## degreesToRadians @@ -458,9 +496,9 @@ Converts an angle in degrees to radians ### Parameters -* `degrees` **[number][3]** angle between 0 and 360 degrees +* `degrees` **[number][12]** angle between 0 and 360 degrees -Returns **[number][3]** angle in radians +Returns **[number][12]** angle in radians ## convertLength @@ -469,11 +507,11 @@ Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, ce ### Parameters -* `length` **[number][3]** to be converted -* `originalUnit` **Units** of the length (optional, default `"kilometers"`) -* `finalUnit` **Units** returned unit (optional, default `"kilometers"`) +* `length` **[number][12]** to be converted +* `originalUnit` **[Units][1]** of the length (optional, default `"kilometers"`) +* `finalUnit` **[Units][1]** returned unit (optional, default `"kilometers"`) -Returns **[number][3]** the converted length +Returns **[number][12]** the converted length ## convertArea @@ -482,11 +520,11 @@ Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, a ### Parameters -* `area` **[number][3]** to be converted -* `originalUnit` **Units** of the distance (optional, default `"meters"`) -* `finalUnit` **Units** returned unit (optional, default `"kilometers"`) +* `area` **[number][12]** to be converted +* `originalUnit` **[AreaUnits][13]** of the distance (optional, default `"meters"`) +* `finalUnit` **[AreaUnits][13]** returned unit (optional, default `"kilometers"`) -Returns **[number][3]** the converted area +Returns **[number][12]** the converted area ## isNumber @@ -526,47 +564,47 @@ turf.isObject('foo') Returns **[boolean][22]** true/false, including false for Arrays and Functions -[1]: https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius +[1]: #units -[2]: https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended +[2]: https://tools.ietf.org/html/rfc7946#section-3.1.4 -[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[3]: https://tools.ietf.org/html/rfc7946#section-3.1.5 -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[4]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[5]: https://tools.ietf.org/html/rfc7946#section-3.1 +[5]: https://tools.ietf.org/html/rfc7946#section-3.1.7 [6]: https://tools.ietf.org/html/rfc7946#section-3.2 -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[7]: https://tools.ietf.org/html/rfc7946#section-3.3 -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[8]: https://tools.ietf.org/html/rfc7946#section-3.1 -[9]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[9]: https://tools.ietf.org/html/rfc7946#section-3.1.8 -[10]: https://tools.ietf.org/html/rfc7946#section-3.3 +[10]: https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius -[11]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[11]: https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended -[12]: https://tools.ietf.org/html/rfc7946#section-3.1.4 +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[13]: Feature +[13]: #areaunits -[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[15]: https://tools.ietf.org/html/rfc7946#section-3.1.5 +[15]: https://tools.ietf.org/html/rfc7946#section-5 -[16]: Feature +[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[17]: https://tools.ietf.org/html/rfc7946#section-3.1.3 +[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[18]: Feature +[18]: https://tools.ietf.org/html/rfc7946#section-3.1.2 -[19]: https://tools.ietf.org/html/rfc7946#section-3.1.7 +[19]: https://developer.mozilla.org/docs/Web/API/Position -[20]: Feature +[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error -[21]: https://tools.ietf.org/html/rfc7946#section-3.1.8 +[21]: https://tools.ietf.org/html/rfc7946#section-3.1.3 [22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/packages/turf-helpers/index.ts b/packages/turf-helpers/index.ts index 8d444160f..f59c4c408 100644 --- a/packages/turf-helpers/index.ts +++ b/packages/turf-helpers/index.ts @@ -18,10 +18,18 @@ import { import { Id } from "./lib/geojson.js"; export * from "./lib/geojson.js"; +/** + * @module helpers + */ + // TurfJS Combined Types export type Coord = Feature | Point | Position; -// TurfJS String Types +/** + * Linear measurement units. + * + * @typedef + */ export type Units = | "meters" | "metres" @@ -38,28 +46,53 @@ export type Units = | "feet" | "radians" | "degrees"; + +/** + * Area measurement units. + * + * @typedef + */ export type AreaUnits = | Exclude | "acres" | "hectares"; + +/** + * Grid types. + * + * @typedef + */ export type Grid = "point" | "square" | "hex" | "triangle"; + +/** + * Shorthand corner identifiers. + * + * @typedef + */ export type Corners = "sw" | "se" | "nw" | "ne" | "center" | "centroid"; +/** + * Geometries made up of lines i.e. lines and polygons. + * + * @typedef + */ export type Lines = LineString | MultiLineString | Polygon | MultiPolygon; + +/** + * Convenience type for all possible GeoJSON. + * + * @typedef + */ export type AllGeoJSON = | Feature | FeatureCollection | Geometry | GeometryCollection; -/** - * @module helpers - */ - /** * The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The {@link https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius mean radius} was selected because it is {@link https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended recommended } by the Haversine formula (used by turf/distance) to reduce error. - * @memberof helpers - * @type {number} + * + * @constant */ export const earthRadius = 6371008.8; @@ -68,8 +101,7 @@ export const earthRadius = 6371008.8; * * Keys are the name of the unit, values are the number of that unit in a single radian * - * @memberof helpers - * @type {Object} + * @constant */ export const factors: Record = { centimeters: earthRadius * 100, @@ -93,8 +125,7 @@ export const factors: Record = { * Area of measurement factors based on 1 square meter. * - * @memberof helpers - * @type {Object} + * @constant */ export const areaFactors: Record = { acres: 0.000247105, @@ -117,13 +148,13 @@ export const areaFactors: Record = { /** * Wraps a GeoJSON {@link Geometry} in a GeoJSON {@link Feature}. * - * @name feature - * @param {Geometry} geometry input geometry - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {GeometryObject} geometry input geometry + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a GeoJSON Feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a GeoJSON Feature * @example * var geometry = { * "type": "Point", @@ -158,8 +189,8 @@ export function feature< * Creates a GeoJSON {@link Geometry} from a Geometry string type & coordinates. * For GeometryCollection type use `helpers.geometryCollection` * - * @name geometry - * @param {string} type Geometry Type + * @function + * @param {("Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon")} type Geometry Type * @param {Array} coordinates Coordinates * @param {Object} [options={}] Optional Parameters * @returns {Geometry} a GeoJSON Geometry @@ -201,13 +232,13 @@ export function geometry( /** * Creates a {@link Point} {@link Feature} from a Position. * - * @name point - * @param {Array} coordinates longitude, latitude position (each in decimal degrees) - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position} coordinates longitude, latitude position (each in decimal degrees) + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a Point feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a Point feature * @example * var point = turf.point([-75.343, 39.984]); * @@ -241,13 +272,13 @@ export function point

( /** * Creates a {@link Point} {@link FeatureCollection} from an Array of Point coordinates. * - * @name points - * @param {Array>} coordinates an array of Points - * @param {Object} [properties={}] Translate these properties to each Feature + * @function + * @param {Position[]} coordinates an array of Points + * @param {GeoJsonProperties} [properties={}] Translate these properties to each Feature * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] * associated with the FeatureCollection - * @param {string|number} [options.id] Identifier associated with the FeatureCollection + * @param {Id} [options.id] Identifier associated with the FeatureCollection * @returns {FeatureCollection} Point Feature * @example * var points = turf.points([ @@ -274,13 +305,13 @@ export function points

( /** * Creates a {@link Polygon} {@link Feature} from an Array of LinearRings. * - * @name polygon - * @param {Array>>} coordinates an array of LinearRings - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[][]} coordinates an array of LinearRings + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} Polygon Feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} Polygon Feature * @example * var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' }); * @@ -319,13 +350,13 @@ export function polygon

( /** * Creates a {@link Polygon} {@link FeatureCollection} from an Array of Polygon coordinates. * - * @name polygons - * @param {Array>>>} coordinates an array of Polygon coordinates - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[][][]} coordinates an array of Polygon coordinates + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the FeatureCollection - * @returns {FeatureCollection} Polygon FeatureCollection + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the FeatureCollection + * @returns {FeatureCollection} Polygon FeatureCollection * @example * var polygons = turf.polygons([ * [[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], @@ -350,13 +381,13 @@ export function polygons

( /** * Creates a {@link LineString} {@link Feature} from an Array of Positions. * - * @name lineString - * @param {Array>} coordinates an array of Positions - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[]} coordinates an array of Positions + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} LineString Feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} LineString Feature * @example * var linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'}); * var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'}); @@ -382,14 +413,14 @@ export function lineString

( /** * Creates a {@link LineString} {@link FeatureCollection} from an Array of LineString coordinates. * - * @name lineStrings - * @param {Array>>} coordinates an array of LinearRings - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[][]} coordinates an array of LinearRings + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] * associated with the FeatureCollection - * @param {string|number} [options.id] Identifier associated with the FeatureCollection - * @returns {FeatureCollection} LineString FeatureCollection + * @param {Id} [options.id] Identifier associated with the FeatureCollection + * @returns {FeatureCollection} LineString FeatureCollection * @example * var linestrings = turf.lineStrings([ * [[-24, 63], [-23, 60], [-25, 65], [-20, 69]], @@ -414,12 +445,12 @@ export function lineStrings

( /** * Takes one or more {@link Feature|Features} and creates a {@link FeatureCollection}. * - * @name featureCollection - * @param {Feature[]} features input features + * @function + * @param {Array>} features input features * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {FeatureCollection} FeatureCollection of Features + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {FeatureCollection} FeatureCollection of Features * @example * var locationA = turf.point([-75.343, 39.984], {name: 'Location A'}); * var locationB = turf.point([-75.833, 39.284], {name: 'Location B'}); @@ -452,16 +483,16 @@ export function featureCollection< } /** - * Creates a {@link Feature} based on a + * Creates a {@link Feature}<{@link MultiLineString}> based on a * coordinate array. Properties can be added optionally. * - * @name multiLineString - * @param {Array>>} coordinates an array of LineStrings - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[][]} coordinates an array of LineStrings + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a MultiLineString feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a MultiLineString feature * @throws {Error} if no coordinates are passed * @example * var multiLine = turf.multiLineString([[[0,0],[10,10]]]); @@ -483,16 +514,16 @@ export function multiLineString< } /** - * Creates a {@link Feature} based on a + * Creates a {@link Feature}<{@link MultiPoint}> based on a * coordinate array. Properties can be added optionally. * - * @name multiPoint - * @param {Array>} coordinates an array of Positions - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[]} coordinates an array of Positions + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a MultiPoint feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a MultiPoint feature * @throws {Error} if no coordinates are passed * @example * var multiPt = turf.multiPoint([[0,0],[10,10]]); @@ -512,16 +543,16 @@ export function multiPoint

( } /** - * Creates a {@link Feature} based on a + * Creates a {@link Feature}<{@link MultiPolygon}> based on a * coordinate array. Properties can be added optionally. * - * @name multiPolygon - * @param {Array>>>} coordinates an array of Polygons - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Position[][][]} coordinates an array of Polygons + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a multipolygon feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a multipolygon feature * @throws {Error} if no coordinates are passed * @example * var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]); @@ -542,16 +573,16 @@ export function multiPolygon

( } /** - * Creates a {@link Feature} based on a + * Creates a Feature based on a * coordinate array. Properties can be added optionally. * - * @name geometryCollection - * @param {Array} geometries an array of GeoJSON Geometries - * @param {Object} [properties={}] an Object of key-value pairs to add as properties + * @function + * @param {Array} geometries an array of GeoJSON Geometries + * @param {GeoJsonProperties} [properties={}] an Object of key-value pairs to add as properties * @param {Object} [options={}] Optional Parameters - * @param {Array} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature - * @param {string|number} [options.id] Identifier associated with the Feature - * @returns {Feature} a GeoJSON GeometryCollection Feature + * @param {BBox} [options.bbox] Bounding Box Array [west, south, east, north] associated with the Feature + * @param {Id} [options.id] Identifier associated with the Feature + * @returns {Feature} a GeoJSON GeometryCollection Feature * @example * var pt = turf.geometry("Point", [100, 0]); * var line = turf.geometry("LineString", [[101, 0], [102, 1]]); @@ -578,6 +609,7 @@ export function geometryCollection< /** * Round number to precision * + * @function * @param {number} num Number * @param {number} [precision=0] Precision * @returns {number} rounded number @@ -600,9 +632,9 @@ export function round(num: number, precision = 0): number { * Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet * - * @name radiansToLength + * @function * @param {number} radians in radians across the sphere - * @param {string} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, + * @param {Units} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, * meters, kilometres, kilometers. * @returns {number} distance */ @@ -621,9 +653,9 @@ export function radiansToLength( * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet * - * @name lengthToRadians + * @function * @param {number} distance in real units - * @param {string} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, + * @param {Units} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, * meters, kilometres, kilometers. * @returns {number} radians */ @@ -642,9 +674,9 @@ export function lengthToRadians( * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees * Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet * - * @name lengthToDegrees + * @function * @param {number} distance in real units - * @param {string} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, + * @param {Units} [units="kilometers"] can be degrees, radians, miles, inches, yards, metres, * meters, kilometres, kilometers. * @returns {number} degrees */ @@ -656,7 +688,7 @@ export function lengthToDegrees(distance: number, units?: Units): number { * Converts any bearing angle from the north line direction (positive clockwise) * and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line * - * @name bearingToAzimuth + * @function * @param {number} bearing angle, between -180 and +180 degrees * @returns {number} angle between 0 and 360 degrees */ @@ -672,7 +704,7 @@ export function bearingToAzimuth(bearing: number): number { * Converts any azimuth angle from the north line direction (positive clockwise) * and returns an angle between -180 and +180 degrees (positive clockwise), 0 being the north line * - * @name azimuthToBearing + * @function * @param {number} angle between 0 and 360 degrees * @returns {number} bearing between -180 and +180 degrees */ @@ -692,7 +724,7 @@ export function azimuthToBearing(angle: number): number { /** * Converts an angle in radians to degrees * - * @name radiansToDegrees + * @function * @param {number} radians angle in radians * @returns {number} degrees between 0 and 360 degrees */ @@ -705,7 +737,7 @@ export function radiansToDegrees(radians: number): number { /** * Converts an angle in degrees to radians * - * @name degreesToRadians + * @function * @param {number} degrees angle between 0 and 360 degrees * @returns {number} angle in radians */ @@ -719,6 +751,7 @@ export function degreesToRadians(degrees: number): number { * Converts a length to the requested unit. * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet * + * @function * @param {number} length to be converted * @param {Units} [originalUnit="kilometers"] of the length * @param {Units} [finalUnit="kilometers"] returned unit @@ -738,9 +771,11 @@ export function convertLength( /** * Converts a area to the requested unit. * Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares + * + * @function * @param {number} area to be converted - * @param {Units} [originalUnit="meters"] of the distance - * @param {Units} [finalUnit="kilometers"] returned unit + * @param {AreaUnits} [originalUnit="meters"] of the distance + * @param {AreaUnits} [finalUnit="kilometers"] returned unit * @returns {number} the converted area */ export function convertArea( @@ -768,7 +803,8 @@ export function convertArea( /** * isNumber * - * @param {*} num Number to validate + * @function + * @param {any} num Number to validate * @returns {boolean} true/false * @example * turf.isNumber(123) @@ -783,7 +819,8 @@ export function isNumber(num: any): boolean { /** * isObject * - * @param {*} input variable to validate + * @function + * @param {any} input variable to validate * @returns {boolean} true/false, including false for Arrays and Functions * @example * turf.isObject({elevation: 10}) @@ -799,7 +836,7 @@ export function isObject(input: any): boolean { * Validate BBox * * @private - * @param {Array} bbox BBox to validate + * @param {any} bbox BBox to validate * @returns {void} * @throws {Error} if BBox is not valid * @example @@ -837,7 +874,7 @@ export function validateBBox(bbox: any): void { * Validate Id * * @private - * @param {string|number} id Id to validate + * @param {any} id Id to validate * @returns {void} * @throws {Error} if Id is not valid * @example diff --git a/packages/turf-hex-grid/index.ts b/packages/turf-hex-grid/index.ts index 0ce997aac..acf7f8f19 100644 --- a/packages/turf-hex-grid/index.ts +++ b/packages/turf-hex-grid/index.ts @@ -14,7 +14,7 @@ import { polygon, featureCollection, Units } from "@turf/helpers"; * hexagons or triangles ({@link Polygon} features) aligned in an "odd-q" vertical grid as * described in [Hexagonal Grids](http://www.redblobgames.com/grids/hexagons/). * - * @name hexGrid + * @function * @param {BBox} bbox extent in [minX, minY, maxX, maxY] order * @param {number} cellSide length of the side of the the hexagons or triangles, in units. It will also coincide with the * radius of the circumcircle of the hexagons. diff --git a/packages/turf-interpolate/index.js b/packages/turf-interpolate/index.js index 02c0bb5cf..e79290a4e 100644 --- a/packages/turf-interpolate/index.js +++ b/packages/turf-interpolate/index.js @@ -13,7 +13,7 @@ import { collectionOf } from "@turf/invariant"; /** * Takes a set of points and estimates their 'property' values on a grid using the [Inverse Distance Weighting (IDW) method](https://en.wikipedia.org/wiki/Inverse_distance_weighting). * - * @name interpolate + * @function * @param {FeatureCollection} points with known value * @param {number} cellSize the distance across each grid point * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-intersect/index.ts b/packages/turf-intersect/index.ts index f8f3e8050..9e97dbe8b 100644 --- a/packages/turf-intersect/index.ts +++ b/packages/turf-intersect/index.ts @@ -13,7 +13,7 @@ import polygonClipping from "polygon-clipping"; * Takes {@link Polygon|polygon} or {@link MultiPolygon|multi-polygon} geometries and * finds their polygonal intersection. If they don't intersect, returns null. * - * @name intersect + * @function * @param {FeatureCollection} features the features to intersect * @param {Object} [options={}] Optional Parameters * @param {Object} [options.properties={}] Translate GeoJSON Properties to Feature diff --git a/packages/turf-invariant/README.md b/packages/turf-invariant/README.md index a885eebbb..381e2d58e 100644 --- a/packages/turf-invariant/README.md +++ b/packages/turf-invariant/README.md @@ -64,6 +64,8 @@ Enforce expectations about types of GeoJSON objects for Turf. * Throws **[Error][9]** if value is not the expected type. +Returns **void** + ## featureOf Enforce expectations about types of [Feature][5] inputs for Turf. @@ -79,6 +81,8 @@ Internally this uses [geojsonType][10] to judge geometry types. * Throws **[Error][9]** error if value is not the expected type. +Returns **void** + ## collectionOf Enforce expectations about types of [FeatureCollection][11] inputs for Turf. diff --git a/packages/turf-invariant/index.ts b/packages/turf-invariant/index.ts index c544d3c75..a672b17bd 100644 --- a/packages/turf-invariant/index.ts +++ b/packages/turf-invariant/index.ts @@ -14,7 +14,7 @@ import { isNumber } from "@turf/helpers"; /** * Unwrap a coordinate from a Point Feature, Geometry or a single coordinate. * - * @name getCoord + * @function * @param {Array|Geometry|Feature} coord GeoJSON Point or an Array of numbers * @returns {Array} coordinates * @example @@ -55,7 +55,7 @@ function getCoord(coord: Feature | Point | number[]): number[] { /** * Unwrap coordinates from a Feature, Geometry Object or an Array * - * @name getCoords + * @function * @param {Array|Geometry|Feature} coords Feature, Geometry Object or an Array * @returns {Array} coordinates * @example @@ -97,7 +97,7 @@ function getCoords< /** * Checks if coordinates contains a number * - * @name containsNumber + * @function * @param {Array} coordinates GeoJSON Coordinates * @returns {boolean} true if Array contains a number */ @@ -119,7 +119,7 @@ function containsNumber(coordinates: any[]): boolean { /** * Enforce expectations about types of GeoJSON objects for Turf. * - * @name geojsonType + * @function * @param {GeoJSON} value any GeoJSON object * @param {string} type expected GeoJSON type * @param {string} name name of calling function @@ -146,7 +146,7 @@ function geojsonType(value: any, type: string, name: string): void { * Enforce expectations about types of {@link Feature} inputs for Turf. * Internally this uses {@link geojsonType} to judge geometry types. * - * @name featureOf + * @function * @param {Feature} feature a feature with an expected geometry type * @param {string} type expected GeoJSON type * @param {string} name name of calling function @@ -180,7 +180,7 @@ function featureOf(feature: Feature, type: string, name: string): void { * Enforce expectations about types of {@link FeatureCollection} inputs for Turf. * Internally this uses {@link geojsonType} to judge geometry types. * - * @name collectionOf + * @function * @param {FeatureCollection} featureCollection a FeatureCollection for which features will be judged * @param {string} type expected GeoJSON type * @param {string} name name of calling function diff --git a/packages/turf-isobands/index.ts b/packages/turf-isobands/index.ts index b03e2f26b..7f7ab8a50 100644 --- a/packages/turf-isobands/index.ts +++ b/packages/turf-isobands/index.ts @@ -34,7 +34,7 @@ type GroupedRings = * Takes a square or rectangular grid {@link FeatureCollection} of {@link Point} features with z-values and an array of * value breaks and generates filled contour isobands. * - * @name isobands + * @function * @param {FeatureCollection} pointGrid input points - must be square or rectangular * @param {Array} breaks where to draw contours * @param {Object} [options={}] options on output diff --git a/packages/turf-isolines/index.ts b/packages/turf-isolines/index.ts index bade82833..92080bfc3 100644 --- a/packages/turf-isolines/index.ts +++ b/packages/turf-isolines/index.ts @@ -17,7 +17,7 @@ import { * Takes a grid {@link FeatureCollection} of {@link Point} features with z-values and an array of * value breaks and generates [isolines](https://en.wikipedia.org/wiki/Contour_line). * - * @name isolines + * @function * @param {FeatureCollection} pointGrid input points * @param {Array} breaks values of `zProperty` where to draw isolines * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-kinks/index.ts b/packages/turf-kinks/index.ts index 331068832..88bae8dcf 100644 --- a/packages/turf-kinks/index.ts +++ b/packages/turf-kinks/index.ts @@ -14,7 +14,7 @@ import { point } from "@turf/helpers"; * {@link MultiPolygon|multi-polygon} or {@link Polygon|polygon} and * returns {@link Point|points} at all self-intersections. * - * @name kinks + * @function * @param {Feature} featureIn input feature * @returns {FeatureCollection} self-intersections * @example diff --git a/packages/turf-length/index.ts b/packages/turf-length/index.ts index 989013c76..fb861fc33 100644 --- a/packages/turf-length/index.ts +++ b/packages/turf-length/index.ts @@ -6,7 +6,7 @@ import { segmentReduce } from "@turf/meta"; /** * Takes a {@link GeoJSON} and measures its length in the specified units, {@link (Multi)Point}'s distance are ignored. * - * @name length + * @function * @param {Feature} geojson GeoJSON to measure * @param {Object} [options={}] Optional parameters * @param {string} [options.units=kilometers] can be degrees, radians, miles, or kilometers diff --git a/packages/turf-line-arc/index.ts b/packages/turf-line-arc/index.ts index 078b5850e..5c988589a 100644 --- a/packages/turf-line-arc/index.ts +++ b/packages/turf-line-arc/index.ts @@ -7,7 +7,7 @@ import { Coord, lineString, Units } from "@turf/helpers"; * Creates a circular arc, of a circle of the given radius and center point, between bearing1 and bearing2; * 0 bearing is North of center point, positive clockwise. * - * @name lineArc + * @function * @param {Coord} center center point * @param {number} radius radius of the circle * @param {number} bearing1 angle, in decimal degrees, of the first radius of the arc diff --git a/packages/turf-line-chunk/index.js b/packages/turf-line-chunk/index.js index d8f7e1bdb..02b6a0a26 100644 --- a/packages/turf-line-chunk/index.js +++ b/packages/turf-line-chunk/index.js @@ -7,7 +7,7 @@ import { featureCollection, isObject } from "@turf/helpers"; * Divides a {@link LineString} into chunks of a specified length. * If the line is shorter than the segment length then the original line is returned. * - * @name lineChunk + * @function * @param {FeatureCollection|Geometry|Feature} geojson the lines to split * @param {number} segmentLength how long to make each segment * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-line-intersect/index.ts b/packages/turf-line-intersect/index.ts index e4c83d30e..3723bdba2 100644 --- a/packages/turf-line-intersect/index.ts +++ b/packages/turf-line-intersect/index.ts @@ -14,7 +14,7 @@ import { sweeplineIntersections as findIntersections } from "./lib/sweepline-int /** * Takes any LineString or Polygon GeoJSON and returns the intersecting point(s). * - * @name lineIntersect + * @function * @param {GeoJSON} line1 any LineString or Polygon * @param {GeoJSON} line2 any LineString or Polygon * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-line-offset/index.js b/packages/turf-line-offset/index.js index 1c936c4b2..583d17816 100644 --- a/packages/turf-line-offset/index.js +++ b/packages/turf-line-offset/index.js @@ -11,7 +11,7 @@ import { intersection } from "./lib/intersection.js"; /** * Takes a {@link LineString|line} and returns a {@link LineString|line} at offset by the specified distance. * - * @name lineOffset + * @function * @param {Geometry|Feature} geojson input GeoJSON * @param {number} distance distance to offset the line (can be of negative value) * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-line-overlap/index.ts b/packages/turf-line-overlap/index.ts index 8027d2747..74d477a81 100644 --- a/packages/turf-line-overlap/index.ts +++ b/packages/turf-line-overlap/index.ts @@ -19,7 +19,7 @@ import equal from "fast-deep-equal"; /** * Takes any LineString or Polygon and returns the overlapping lines between both features. * - * @name lineOverlap + * @function * @param {Geometry|Feature} line1 any LineString or Polygon * @param {Geometry|Feature} line2 any LineString or Polygon * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-line-segment/index.ts b/packages/turf-line-segment/index.ts index 5c518277f..10f795f47 100644 --- a/packages/turf-line-segment/index.ts +++ b/packages/turf-line-segment/index.ts @@ -15,7 +15,7 @@ import { flattenEach } from "@turf/meta"; * Creates a {@link FeatureCollection} of 2-vertex {@link LineString} segments from a * {@link LineString|(Multi)LineString} or {@link Polygon|(Multi)Polygon}. * - * @name lineSegment + * @function * @param {GeoJSON} geojson GeoJSON Polygon or LineString * @returns {FeatureCollection} 2-vertex line segments * @example diff --git a/packages/turf-line-slice-along/index.js b/packages/turf-line-slice-along/index.js index 9d7c11699..d26d00d7e 100644 --- a/packages/turf-line-slice-along/index.js +++ b/packages/turf-line-slice-along/index.js @@ -10,7 +10,7 @@ import { lineString, isObject } from "@turf/helpers"; * * This can be useful for extracting only the part of a route between two distances. * - * @name lineSliceAlong + * @function * @param {Feature|LineString} line input line * @param {number} startDist distance along the line to starting point * @param {number} stopDist distance along the line to ending point diff --git a/packages/turf-line-slice/index.js b/packages/turf-line-slice/index.js index dc66da414..b4fdbc7b7 100644 --- a/packages/turf-line-slice/index.js +++ b/packages/turf-line-slice/index.js @@ -9,7 +9,7 @@ import { nearestPointOnLine } from "@turf/nearest-point-on-line"; * * This can be useful for extracting only the part of a route between waypoints. * - * @name lineSlice + * @function * @param {Coord} startPt starting point * @param {Coord} stopPt stopping point * @param {Feature|LineString} line line to slice diff --git a/packages/turf-line-split/index.js b/packages/turf-line-split/index.js index 81d33017b..cfbdfb584 100644 --- a/packages/turf-line-split/index.js +++ b/packages/turf-line-split/index.js @@ -12,7 +12,7 @@ import { lineString, featureCollection } from "@turf/helpers"; /** * Split a LineString by another GeoJSON Feature. * - * @name lineSplit + * @function * @param {Feature} line LineString Feature to split * @param {Feature} splitter Feature used to split line * @returns {FeatureCollection} Split LineStrings diff --git a/packages/turf-line-to-polygon/index.ts b/packages/turf-line-to-polygon/index.ts index 78fb03141..cdf859cf1 100644 --- a/packages/turf-line-to-polygon/index.ts +++ b/packages/turf-line-to-polygon/index.ts @@ -15,7 +15,7 @@ import { clone } from "@turf/clone"; /** * Converts (Multi)LineString(s) to Polygon(s). * - * @name lineToPolygon + * @function * @param {FeatureCollection|Feature} lines Features to convert * @param {Object} [options={}] Optional parameters * @param {Object} [options.properties={}] translates GeoJSON properties to Feature diff --git a/packages/turf-mask/index.ts b/packages/turf-mask/index.ts index 43abb6304..eaca08f2a 100644 --- a/packages/turf-mask/index.ts +++ b/packages/turf-mask/index.ts @@ -13,7 +13,7 @@ import { clone } from "@turf/clone"; * Takes polygons or multipolygons and an optional mask, and returns an exterior * ring polygon with holes. * - * @name mask + * @function * @param {Polygon|MultiPolygon|Feature|FeatureCollection} polygon GeoJSON polygon used as interior rings or holes * @param {Polygon|Feature} [mask] GeoJSON polygon used as the exterior ring (if undefined, the world extent is used) * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-meta/README.md b/packages/turf-meta/README.md index 13dc60352..95dc11e47 100644 --- a/packages/turf-meta/README.md +++ b/packages/turf-meta/README.md @@ -16,15 +16,17 @@ Type: [Function][1] * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. * `geometryIndex` **[number][3]** The current index of the Geometry being processed. +Returns **void** + ## coordEach Iterate over coordinates in any GeoJSON object, similar to Array.forEach() ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (currentCoord, coordIndex, featureIndex, multiFeatureIndex) -* `excludeWrapCoord` **[boolean][7]** whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. (optional, default `false`) +* `geojson` **AllGeoJSON** any GeoJSON object +* `callback` **[coordEachCallback][4]** a method that takes (currentCoord, coordIndex, featureIndex, multiFeatureIndex) +* `excludeWrapCoord` **[boolean][5]** whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. (optional, default `false`) ### Examples @@ -66,7 +68,7 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. * `currentCoord` **[Array][2]<[number][3]>** The current coordinate being processed. * `coordIndex` **[number][3]** The current index of the coordinate being processed. @@ -75,16 +77,18 @@ Type: [Function][1] * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. * `geometryIndex` **[number][3]** The current index of the Geometry being processed. +Returns **Reducer** + ## coordReduce Reduce coordinates in any GeoJSON object, similar to Array.reduce() ### Parameters -* `geojson` **([FeatureCollection][4] | [Geometry][6] | [Feature][5])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (previousValue, currentCoord, coordIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. -* `excludeWrapCoord` **[boolean][7]** whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. (optional, default `false`) +* `geojson` **AllGeoJSON** any GeoJSON object +* `callback` **[coordReduceCallback][6]** a method that takes (previousValue, currentCoord, coordIndex) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. +* `excludeWrapCoord` **[boolean][5]** whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. (optional, default `false`) ### Examples @@ -105,7 +109,7 @@ turf.coordReduce(features, function (previousValue, currentCoord, coordIndex, fe }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## propEachCallback @@ -115,17 +119,19 @@ Type: [Function][1] ### Parameters -* `currentProperties` **[Object][8]** The current Properties being processed. +* `currentProperties` **[GeoJsonProperties][7]** The current Properties being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. +Returns **void** + ## propEach Iterate over properties in any GeoJSON object, similar to Array.forEach() ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (currentProperties, featureIndex) +* `geojson` **([FeatureCollection][8] | [Feature][7])** any GeoJSON object +* `callback` **[propEachCallback][9]** a method that takes (currentProperties, featureIndex) ### Examples @@ -164,11 +170,13 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentProperties` **any** The current Properties being processed. +* `currentProperties` **[GeoJsonProperties][7]** The current Properties being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. +Returns **Reducer** + ## propReduce Reduce properties in any GeoJSON object into a single value, @@ -177,9 +185,9 @@ the reduction, so an array of all properties is unnecessary. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (previousValue, currentProperties, featureIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Geometry][10])** any GeoJSON object +* `callback` **[propReduceCallback][11]** a method that takes (previousValue, currentProperties, featureIndex) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -197,7 +205,7 @@ turf.propReduce(features, function (previousValue, currentProperties, featureInd }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## featureEachCallback @@ -207,9 +215,11 @@ Type: [Function][1] ### Parameters -* `currentFeature` **[Feature][5]\** The current Feature being processed. +* `currentFeature` **[Feature][7]\** The current Feature being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. +Returns **void** + ## featureEach Iterate over features in any GeoJSON object, similar to @@ -217,8 +227,8 @@ Array.forEach. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (currentFeature, featureIndex) +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[featureEachCallback][13]** a method that takes (currentFeature, featureIndex) ### Examples @@ -257,20 +267,22 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentFeature` **[Feature][5]** The current Feature being processed. +* `currentFeature` **[Feature][7]** The current Feature being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. +Returns **Reducer** + ## featureReduce Reduce features in any GeoJSON object, similar to Array.reduce(). ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (previousValue, currentFeature, featureIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[featureReduceCallback][14]** a method that takes (previousValue, currentFeature, featureIndex) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -288,7 +300,7 @@ turf.featureReduce(features, function (previousValue, currentFeature, featureInd }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## coordAll @@ -296,7 +308,7 @@ Get all coordinates from any GeoJSON object. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object +* `geojson` **AllGeoJSON** any GeoJSON object ### Examples @@ -320,11 +332,13 @@ Type: [Function][1] ### Parameters -* `currentGeometry` **[Geometry][6]** The current Geometry being processed. +* `currentGeometry` **[GeometryObject][10]** The current Geometry being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. -* `featureProperties` **[Object][8]** The current Feature Properties being processed. -* `featureBBox` **[Array][2]<[number][3]>** The current Feature BBox being processed. -* `featureId` **([number][3] | [string][9])** The current Feature Id being processed. +* `featureProperties` **[GeoJsonProperties][7]** The current Feature Properties being processed. +* `featureBBox` **[BBox][15]** The current Feature BBox being processed. +* `featureId` **Id** The current Feature Id being processed. + +Returns **void** ## geomEach @@ -332,8 +346,8 @@ Iterate over each geometry in any GeoJSON object, similar to Array.forEach() ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (currentGeometry, featureIndex, featureProperties, featureBBox, featureId) +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Geometry][10] | [GeometryObject][10] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[geomEachCallback][16]** a method that takes (currentGeometry, featureIndex, featureProperties, featureBBox, featureId) ### Examples @@ -375,13 +389,15 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentGeometry` **[Geometry][6]** The current Geometry being processed. +* `currentGeometry` **[GeometryObject][10]** The current Geometry being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. -* `featureProperties` **[Object][8]** The current Feature Properties being processed. -* `featureBBox` **[Array][2]<[number][3]>** The current Feature BBox being processed. -* `featureId` **([number][3] | [string][9])** The current Feature Id being processed. +* `featureProperties` **[GeoJsonProperties][7]** The current Feature Properties being processed. +* `featureBBox` **[BBox][15]** The current Feature BBox being processed. +* `featureId` **Id** The current Feature Id being processed. + +Returns **Reducer** ## geomReduce @@ -389,9 +405,9 @@ Reduce geometry in any GeoJSON object, similar to Array.reduce(). ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (previousValue, currentGeometry, featureIndex, featureProperties, featureBBox, featureId) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `geojson` **([FeatureCollection][8] | [Feature][7] | [GeometryObject][10] | [GeometryCollection][12] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[geomReduceCallback][17]** a method that takes (previousValue, currentGeometry, featureIndex, featureProperties, featureBBox, featureId) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -412,7 +428,7 @@ turf.geomReduce(features, function (previousValue, currentGeometry, featureIndex }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## flattenEachCallback @@ -422,10 +438,12 @@ Type: [Function][1] ### Parameters -* `currentFeature` **[Feature][5]** The current flattened feature being processed. +* `currentFeature` **[Feature][7]** The current flattened feature being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. +Returns **void** + ## flattenEach Iterate over flattened features in any GeoJSON object, similar to @@ -433,8 +451,8 @@ Array.forEach. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (currentFeature, featureIndex, multiFeatureIndex) +* `geojson` **([FeatureCollection][8] | [Feature][7] | [GeometryObject][10] | [GeometryCollection][12] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[flattenEachCallback][18]** a method that takes (currentFeature, featureIndex, multiFeatureIndex) ### Examples @@ -451,6 +469,8 @@ turf.flattenEach(features, function (currentFeature, featureIndex, multiFeatureI }); ``` +Returns **void** + ## flattenReduceCallback Callback for flattenReduce @@ -472,21 +492,23 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentFeature` **[Feature][5]** The current Feature being processed. +* `currentFeature` **[Feature][7]** The current Feature being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. +Returns **Reducer** + ## flattenReduce Reduce flattened features in any GeoJSON object, similar to Array.reduce(). ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON object -* `callback` **[Function][1]** a method that takes (previousValue, currentFeature, featureIndex, multiFeatureIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `geojson` **([FeatureCollection][8] | [Feature][7] | [GeometryObject][10] | [GeometryCollection][12] | [Feature][7]<[GeometryCollection][12]>)** any GeoJSON object +* `callback` **[flattenReduceCallback][19]** a method that takes (previousValue, currentFeature, featureIndex, multiFeatureIndex) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -505,7 +527,7 @@ turf.flattenReduce(features, function (previousValue, currentFeature, featureInd }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## segmentEachCallback @@ -515,7 +537,7 @@ Type: [Function][1] ### Parameters -* `currentSegment` **[Feature][5]<[LineString][10]>** The current Segment being processed. +* `currentSegment` **[Feature][7]<[LineString][20]>** The current Segment being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. * `geometryIndex` **[number][3]** The current index of the Geometry being processed. @@ -530,8 +552,8 @@ Iterate over 2-vertex line segment in any GeoJSON object, similar to Array.forEa ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON -* `callback` **[Function][1]** a method that takes (currentSegment, featureIndex, multiFeatureIndex, geometryIndex, segmentIndex) +* `geojson` **AllGeoJSON** any GeoJSON +* `callback` **[segmentEachCallback][21]** a method that takes (currentSegment, featureIndex, multiFeatureIndex, geometryIndex, segmentIndex) ### Examples @@ -577,14 +599,16 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentSegment` **[Feature][5]<[LineString][10]>** The current Segment being processed. +* `currentSegment` **[Feature][7]<[LineString][20]>** The current Segment being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed. * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed. * `geometryIndex` **[number][3]** The current index of the Geometry being processed. * `segmentIndex` **[number][3]** The current index of the Segment being processed. +Returns **Reducer** + ## segmentReduce Reduce 2-vertex line segment in any GeoJSON object, similar to Array.reduce() @@ -592,9 +616,9 @@ Reduce 2-vertex line segment in any GeoJSON object, similar to Array.reduce() ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** any GeoJSON -* `callback` **[Function][1]** a method that takes (previousValue, currentSegment, currentIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Geometry][10])** any GeoJSON +* `callback` **[segmentReduceCallback][22]** a method that takes (previousValue, currentSegment, currentIndex) +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -620,7 +644,7 @@ var total = turf.segmentReduce(polygon, function (previousValue) { }, initialValue); ``` -Returns **void** +Returns **Reducer** ## lineEachCallback @@ -630,11 +654,13 @@ Type: [Function][1] ### Parameters -* `currentLine` **[Feature][5]<[LineString][10]>** The current LineString|LinearRing being processed +* `currentLine` **[Feature][7]<[LineString][20]>** The current LineString|LinearRing being processed * `featureIndex` **[number][3]** The current index of the Feature being processed * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed * `geometryIndex` **[number][3]** The current index of the Geometry being processed +Returns **void** + ## lineEach Iterate over line or ring coordinates in LineString, Polygon, MultiLineString, MultiPolygon Features or Geometries, @@ -642,8 +668,8 @@ similar to Array.forEach. ### Parameters -* `geojson` **([Geometry][6] | [Feature][5]<([LineString][10] | [Polygon][11] | [MultiLineString][12] | [MultiPolygon][13])>)** object -* `callback` **[Function][1]** a method that takes (currentLine, featureIndex, multiFeatureIndex, geometryIndex) +* `geojson` **([FeatureCollection][8]\ | [Feature][7]\ | Lines | [Feature][7]<[GeometryCollection][12]> | [GeometryCollection][12])** object +* `callback` **[lineEachCallback][23]** a method that takes (currentLine, featureIndex, multiFeatureIndex, geometryIndex) ### Examples @@ -661,6 +687,8 @@ turf.lineEach(multiLine, function (currentLine, featureIndex, multiFeatureIndex, }); ``` +Returns **void** + ## lineReduceCallback Callback for lineReduce @@ -682,22 +710,24 @@ Type: [Function][1] ### Parameters -* `previousValue` **any** The accumulated value previously returned in the last invocation +* `previousValue` **Reducer** The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. -* `currentLine` **[Feature][5]<[LineString][10]>** The current LineString|LinearRing being processed. +* `currentLine` **[Feature][7]<[LineString][20]>** The current LineString|LinearRing being processed. * `featureIndex` **[number][3]** The current index of the Feature being processed * `multiFeatureIndex` **[number][3]** The current index of the Multi-Feature being processed * `geometryIndex` **[number][3]** The current index of the Geometry being processed +Returns **Reducer** + ## lineReduce Reduce features in any GeoJSON object, similar to Array.reduce(). ### Parameters -* `geojson` **([Geometry][6] | [Feature][5]<([LineString][10] | [Polygon][11] | [MultiLineString][12] | [MultiPolygon][13])>)** object +* `geojson` **([FeatureCollection][8]\ | [Feature][7]\ | Lines | [Feature][7]<[GeometryCollection][12]> | [GeometryCollection][12])** object * `callback` **[Function][1]** a method that takes (previousValue, currentLine, featureIndex, multiFeatureIndex, geometryIndex) -* `initialValue` **any?** Value to use as the first argument to the first call of the callback. +* `initialValue` **Reducer?** Value to use as the first argument to the first call of the callback. ### Examples @@ -717,7 +747,7 @@ turf.lineReduce(multiPoly, function (previousValue, currentLine, featureIndex, m }); ``` -Returns **any** The value that results from the reduction. +Returns **Reducer** The value that results from the reduction. ## findSegment @@ -728,16 +758,16 @@ Point & MultiPoint will always return null. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** Any GeoJSON Feature or Geometry -* `options` **[Object][8]** Optional parameters (optional, default `{}`) +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Geometry][10])** Any GeoJSON Feature or Geometry +* `options` **[Object][24]** Optional parameters (optional, default `{}`) * `options.featureIndex` **[number][3]** Feature Index (optional, default `0`) * `options.multiFeatureIndex` **[number][3]** Multi-Feature Index (optional, default `0`) * `options.geometryIndex` **[number][3]** Geometry Index (optional, default `0`) * `options.segmentIndex` **[number][3]** Segment Index (optional, default `0`) - * `options.properties` **[Object][8]** Translate Properties to output LineString (optional, default `{}`) - * `options.bbox` **[BBox][14]** Translate BBox to output LineString (optional, default `{}`) - * `options.id` **([number][3] | [string][9])** Translate Id to output LineString (optional, default `{}`) + * `options.properties` **[Object][24]** Translate Properties to output LineString (optional, default `{}`) + * `options.bbox` **[BBox][15]** Translate BBox to output LineString (optional, default `{}`) + * `options.id` **([number][3] | [string][25])** Translate Id to output LineString (optional, default `{}`) ### Examples @@ -760,7 +790,7 @@ turf.findSegment(multiLine, {multiFeatureIndex: -1, segmentIndex: -1}); // => Feature> ``` -Returns **[Feature][5]<[LineString][10]>** 2-vertex GeoJSON Feature LineString +Returns **[Feature][7]<[LineString][20]>** 2-vertex GeoJSON Feature LineString ## findPoint @@ -770,16 +800,16 @@ Negative indexes are permitted. ### Parameters -* `geojson` **([FeatureCollection][4] | [Feature][5] | [Geometry][6])** Any GeoJSON Feature or Geometry -* `options` **[Object][8]** Optional parameters (optional, default `{}`) +* `geojson` **([FeatureCollection][8] | [Feature][7] | [Geometry][10])** Any GeoJSON Feature or Geometry +* `options` **[Object][24]** Optional parameters (optional, default `{}`) * `options.featureIndex` **[number][3]** Feature Index (optional, default `0`) * `options.multiFeatureIndex` **[number][3]** Multi-Feature Index (optional, default `0`) * `options.geometryIndex` **[number][3]** Geometry Index (optional, default `0`) * `options.coordIndex` **[number][3]** Coord Index (optional, default `0`) - * `options.properties` **[Object][8]** Translate Properties to output Point (optional, default `{}`) - * `options.bbox` **[BBox][14]** Translate BBox to output Point (optional, default `{}`) - * `options.id` **([number][3] | [string][9])** Translate Id to output Point (optional, default `{}`) + * `options.properties` **[Object][24]** Translate Properties to output Point (optional, default `{}`) + * `options.bbox` **[BBox][15]** Translate BBox to output Point (optional, default `{}`) + * `options.id` **([number][3] | [string][25])** Translate Id to output Point (optional, default `{}`) ### Examples @@ -802,7 +832,7 @@ turf.findPoint(multiLine, {multiFeatureIndex: -1, coordIndex: -1}); // => Feature> ``` -Returns **[Feature][5]<[Point][15]>** 2-vertex GeoJSON Feature Point +Returns **[Feature][7]<[Point][26]>** 2-vertex GeoJSON Feature Point [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function @@ -810,29 +840,51 @@ Returns **[Feature][5]<[Point][15]>** 2-vertex GeoJSON Feature Point [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[4]: https://tools.ietf.org/html/rfc7946#section-3.3 +[4]: #coordeachcallback + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[6]: #coordreducecallback + +[7]: https://tools.ietf.org/html/rfc7946#section-3.2 + +[8]: https://tools.ietf.org/html/rfc7946#section-3.3 + +[9]: #propeachcallback + +[10]: https://tools.ietf.org/html/rfc7946#section-3.1 + +[11]: #propreducecallback + +[12]: https://tools.ietf.org/html/rfc7946#section-3.1.8 + +[13]: #featureeachcallback + +[14]: #featurereducecallback + +[15]: https://tools.ietf.org/html/rfc7946#section-5 -[5]: https://tools.ietf.org/html/rfc7946#section-3.2 +[16]: #geomeachcallback -[6]: https://tools.ietf.org/html/rfc7946#section-3.1 +[17]: #geomreducecallback -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[18]: #flatteneachcallback -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[19]: #flattenreducecallback -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[20]: https://tools.ietf.org/html/rfc7946#section-3.1.4 -[10]: https://tools.ietf.org/html/rfc7946#section-3.1.4 +[21]: #segmenteachcallback -[11]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[22]: #segmentreducecallback -[12]: https://tools.ietf.org/html/rfc7946#section-3.1.5 +[23]: #lineeachcallback -[13]: https://tools.ietf.org/html/rfc7946#section-3.1.7 +[24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[14]: https://tools.ietf.org/html/rfc7946#section-5 +[25]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[15]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[26]: https://tools.ietf.org/html/rfc7946#section-3.1.2 diff --git a/packages/turf-meta/index.js b/packages/turf-meta/index.js index d9d42e942..d1fe722c8 100644 --- a/packages/turf-meta/index.js +++ b/packages/turf-meta/index.js @@ -4,19 +4,20 @@ import { feature, point, lineString, isObject } from "@turf/helpers"; * Callback for coordEach * * @callback coordEachCallback - * @param {Array} currentCoord The current coordinate being processed. + * @param {number[]} currentCoord The current coordinate being processed. * @param {number} coordIndex The current index of the coordinate being processed. * @param {number} featureIndex The current index of the Feature being processed. * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed. * @param {number} geometryIndex The current index of the Geometry being processed. + * @returns {void} */ /** * Iterate over coordinates in any GeoJSON object, similar to Array.forEach() * - * @name coordEach - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (currentCoord, coordIndex, featureIndex, multiFeatureIndex) + * @function + * @param {AllGeoJSON} geojson any GeoJSON object + * @param {coordEachCallback} callback a method that takes (currentCoord, coordIndex, featureIndex, multiFeatureIndex) * @param {boolean} [excludeWrapCoord=false] whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. * @returns {void} * @example @@ -202,25 +203,26 @@ function coordEach(geojson, callback, excludeWrapCoord) { * - The currentValue argument is the value of the second element present in the array. * * @callback coordReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. - * @param {Array} currentCoord The current coordinate being processed. + * @param {number[]} currentCoord The current coordinate being processed. * @param {number} coordIndex The current index of the coordinate being processed. * Starts at index 0, if an initialValue is provided, and at index 1 otherwise. * @param {number} featureIndex The current index of the Feature being processed. * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed. * @param {number} geometryIndex The current index of the Geometry being processed. + * @returns {Reducer} */ /** * Reduce coordinates in any GeoJSON object, similar to Array.reduce() * - * @name coordReduce - * @param {FeatureCollection|Geometry|Feature} geojson any GeoJSON object - * @param {Function} callback a method that takes (previousValue, currentCoord, coordIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. + * @function + * @param {AllGeoJSON} geojson any GeoJSON object + * @param {coordReduceCallback} callback a method that takes (previousValue, currentCoord, coordIndex) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. * @param {boolean} [excludeWrapCoord=false] whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. - * @returns {*} The value that results from the reduction. + * @returns {Reducer} The value that results from the reduction. * @example * var features = turf.featureCollection([ * turf.point([26, 37], {"foo": "bar"}), @@ -269,16 +271,17 @@ function coordReduce(geojson, callback, initialValue, excludeWrapCoord) { * Callback for propEach * * @callback propEachCallback - * @param {Object} currentProperties The current Properties being processed. + * @param {GeoJsonProperties} currentProperties The current Properties being processed. * @param {number} featureIndex The current index of the Feature being processed. + * @returns {void} */ /** * Iterate over properties in any GeoJSON object, similar to Array.forEach() * - * @name propEach + * @function * @param {FeatureCollection|Feature} geojson any GeoJSON object - * @param {Function} callback a method that takes (currentProperties, featureIndex) + * @param {propEachCallback} callback a method that takes (currentProperties, featureIndex) * @returns {void} * @example * var features = turf.featureCollection([ @@ -320,10 +323,11 @@ function propEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback propReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. - * @param {*} currentProperties The current Properties being processed. + * @param {GeoJsonProperties} currentProperties The current Properties being processed. * @param {number} featureIndex The current index of the Feature being processed. + * @returns {Reducer} */ /** @@ -331,11 +335,11 @@ function propEach(geojson, callback) { * similar to how Array.reduce works. However, in this case we lazily run * the reduction, so an array of all properties is unnecessary. * - * @name propReduce - * @param {FeatureCollection|Feature} geojson any GeoJSON object - * @param {Function} callback a method that takes (previousValue, currentProperties, featureIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @function + * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object + * @param {propReduceCallback} callback a method that takes (previousValue, currentProperties, featureIndex) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} The value that results from the reduction. * @example * var features = turf.featureCollection([ * turf.point([26, 37], {foo: 'bar'}), @@ -366,15 +370,16 @@ function propReduce(geojson, callback, initialValue) { * @callback featureEachCallback * @param {Feature} currentFeature The current Feature being processed. * @param {number} featureIndex The current index of the Feature being processed. + * @returns {void} */ /** * Iterate over features in any GeoJSON object, similar to * Array.forEach. * - * @name featureEach - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (currentFeature, featureIndex) + * @function + * @param {FeatureCollection|Feature|Feature} geojson any GeoJSON object + * @param {featureEachCallback} callback a method that takes (currentFeature, featureIndex) * @returns {void} * @example * var features = turf.featureCollection([ @@ -412,20 +417,21 @@ function featureEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback featureReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. * @param {Feature} currentFeature The current Feature being processed. * @param {number} featureIndex The current index of the Feature being processed. + * @returns {Reducer} */ /** * Reduce features in any GeoJSON object, similar to Array.reduce(). * - * @name featureReduce - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (previousValue, currentFeature, featureIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @function + * @param {FeatureCollection|Feature|Feature} geojson any GeoJSON object + * @param {featureReduceCallback} callback a method that takes (previousValue, currentFeature, featureIndex) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} The value that results from the reduction. * @example * var features = turf.featureCollection([ * turf.point([26, 37], {"foo": "bar"}), @@ -452,8 +458,8 @@ function featureReduce(geojson, callback, initialValue) { /** * Get all coordinates from any GeoJSON object. * - * @name coordAll - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object + * @function + * @param {AllGeoJSON} geojson any GeoJSON object * @returns {Array>} coordinate position array * @example * var features = turf.featureCollection([ @@ -476,19 +482,20 @@ function coordAll(geojson) { * Callback for geomEach * * @callback geomEachCallback - * @param {Geometry} currentGeometry The current Geometry being processed. + * @param {GeometryObject} currentGeometry The current Geometry being processed. * @param {number} featureIndex The current index of the Feature being processed. - * @param {Object} featureProperties The current Feature Properties being processed. - * @param {Array} featureBBox The current Feature BBox being processed. - * @param {number|string} featureId The current Feature Id being processed. + * @param {GeoJsonProperties} featureProperties The current Feature Properties being processed. + * @param {BBox} featureBBox The current Feature BBox being processed. + * @param {Id} featureId The current Feature Id being processed. + * @returns {void} */ /** * Iterate over each geometry in any GeoJSON object, similar to Array.forEach() * - * @name geomEach - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (currentGeometry, featureIndex, featureProperties, featureBBox, featureId) + * @function + * @param {FeatureCollection|Feature|Geometry|GeometryObject|Feature} geojson any GeoJSON object + * @param {geomEachCallback} callback a method that takes (currentGeometry, featureIndex, featureProperties, featureBBox, featureId) * @returns {void} * @example * var features = turf.featureCollection([ @@ -637,23 +644,24 @@ function geomEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback geomReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. - * @param {Geometry} currentGeometry The current Geometry being processed. + * @param {GeometryObject} currentGeometry The current Geometry being processed. * @param {number} featureIndex The current index of the Feature being processed. - * @param {Object} featureProperties The current Feature Properties being processed. - * @param {Array} featureBBox The current Feature BBox being processed. - * @param {number|string} featureId The current Feature Id being processed. + * @param {GeoJsonProperties} featureProperties The current Feature Properties being processed. + * @param {BBox} featureBBox The current Feature BBox being processed. + * @param {Id} featureId The current Feature Id being processed. + * @returns {Reducer} */ /** * Reduce geometry in any GeoJSON object, similar to Array.reduce(). * - * @name geomReduce - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (previousValue, currentGeometry, featureIndex, featureProperties, featureBBox, featureId) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @function + * @param {FeatureCollection|Feature|GeometryObject|GeometryCollection|Feature} geojson any GeoJSON object + * @param {geomReduceCallback} callback a method that takes (previousValue, currentGeometry, featureIndex, featureProperties, featureBBox, featureId) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} The value that results from the reduction. * @example * var features = turf.featureCollection([ * turf.point([26, 37], {foo: 'bar'}), @@ -704,15 +712,17 @@ function geomReduce(geojson, callback, initialValue) { * @param {Feature} currentFeature The current flattened feature being processed. * @param {number} featureIndex The current index of the Feature being processed. * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed. + * @returns {void} */ /** * Iterate over flattened features in any GeoJSON object, similar to * Array.forEach. * - * @name flattenEach - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (currentFeature, featureIndex, multiFeatureIndex) + * @function + * @param {FeatureCollection|Feature|GeometryObject|GeometryCollection|Feature} geojson any GeoJSON object + * @param {flattenEachCallback} callback a method that takes (currentFeature, featureIndex, multiFeatureIndex) + * @returns {void} * @example * var features = turf.featureCollection([ * turf.point([26, 37], {foo: 'bar'}), @@ -794,21 +804,22 @@ function flattenEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback flattenReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. * @param {Feature} currentFeature The current Feature being processed. * @param {number} featureIndex The current index of the Feature being processed. * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed. + * @returns {Reducer} */ /** * Reduce flattened features in any GeoJSON object, similar to Array.reduce(). * - * @name flattenReduce - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON object - * @param {Function} callback a method that takes (previousValue, currentFeature, featureIndex, multiFeatureIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @function + * @param {FeatureCollection|Feature|GeometryObject|GeometryCollection|Feature} geojson any GeoJSON object + * @param {flattenReduceCallback} callback a method that takes (previousValue, currentFeature, featureIndex, multiFeatureIndex) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} The value that results from the reduction. * @example * var features = turf.featureCollection([ * turf.point([26, 37], {foo: 'bar'}), @@ -862,8 +873,8 @@ function flattenReduce(geojson, callback, initialValue) { * Iterate over 2-vertex line segment in any GeoJSON object, similar to Array.forEach() * (Multi)Point geometries do not contain segments therefore they are ignored during this operation. * - * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON - * @param {Function} callback a method that takes (currentSegment, featureIndex, multiFeatureIndex, geometryIndex, segmentIndex) + * @param {AllGeoJSON} geojson any GeoJSON + * @param {segmentEachCallback} callback a method that takes (currentSegment, featureIndex, multiFeatureIndex, geometryIndex, segmentIndex) * @returns {void} * @example * var polygon = turf.polygon([[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]); @@ -960,13 +971,14 @@ function segmentEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback segmentReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. * @param {Feature} currentSegment The current Segment being processed. * @param {number} featureIndex The current index of the Feature being processed. * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed. * @param {number} geometryIndex The current index of the Geometry being processed. * @param {number} segmentIndex The current index of the Segment being processed. + * @returns {Reducer} */ /** @@ -974,9 +986,9 @@ function segmentEach(geojson, callback) { * (Multi)Point geometries do not contain segments therefore they are ignored during this operation. * * @param {FeatureCollection|Feature|Geometry} geojson any GeoJSON - * @param {Function} callback a method that takes (previousValue, currentSegment, currentIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {void} + * @param {segmentReduceCallback} callback a method that takes (previousValue, currentSegment, currentIndex) + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} * @example * var polygon = turf.polygon([[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]); * @@ -1035,15 +1047,17 @@ function segmentReduce(geojson, callback, initialValue) { * @param {number} featureIndex The current index of the Feature being processed * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed * @param {number} geometryIndex The current index of the Geometry being processed + * @returns {void} */ /** * Iterate over line or ring coordinates in LineString, Polygon, MultiLineString, MultiPolygon Features or Geometries, * similar to Array.forEach. * - * @name lineEach - * @param {Geometry|Feature} geojson object - * @param {Function} callback a method that takes (currentLine, featureIndex, multiFeatureIndex, geometryIndex) + * @function + * @param {FeatureCollection|Feature|Lines|Feature|GeometryCollection} geojson object + * @param {lineEachCallback} callback a method that takes (currentLine, featureIndex, multiFeatureIndex, geometryIndex) + * @returns {void} * @example * var multiLine = turf.multiLineString([ * [[26, 37], [35, 45]], @@ -1106,22 +1120,23 @@ function lineEach(geojson, callback) { * - The currentValue argument is the value of the second element present in the array. * * @callback lineReduceCallback - * @param {*} previousValue The accumulated value previously returned in the last invocation + * @param {Reducer} previousValue The accumulated value previously returned in the last invocation * of the callback, or initialValue, if supplied. * @param {Feature} currentLine The current LineString|LinearRing being processed. * @param {number} featureIndex The current index of the Feature being processed * @param {number} multiFeatureIndex The current index of the Multi-Feature being processed * @param {number} geometryIndex The current index of the Geometry being processed + * @returns {Reducer} */ /** * Reduce features in any GeoJSON object, similar to Array.reduce(). * - * @name lineReduce - * @param {Geometry|Feature} geojson object + * @function + * @param {FeatureCollection|Feature|Lines|Feature|GeometryCollection} geojson object * @param {Function} callback a method that takes (previousValue, currentLine, featureIndex, multiFeatureIndex, geometryIndex) - * @param {*} [initialValue] Value to use as the first argument to the first call of the callback. - * @returns {*} The value that results from the reduction. + * @param {Reducer} [initialValue] Value to use as the first argument to the first call of the callback. + * @returns {Reducer} The value that results from the reduction. * @example * var multiPoly = turf.multiPolygon([ * turf.polygon([[[12,48],[2,41],[24,38],[12,48]], [[9,44],[13,41],[13,45],[9,44]]]), diff --git a/packages/turf-midpoint/index.ts b/packages/turf-midpoint/index.ts index a401c57a1..70ccef3f5 100644 --- a/packages/turf-midpoint/index.ts +++ b/packages/turf-midpoint/index.ts @@ -9,7 +9,7 @@ import { Coord } from "@turf/helpers"; * calculated geodesically, meaning the curvature of the earth is taken into * account. * - * @name midpoint + * @function * @param {Coord} point1 first point * @param {Coord} point2 second point * @returns {Feature} a point midway between `pt1` and `pt2` diff --git a/packages/turf-moran-index/README.md b/packages/turf-moran-index/README.md index ce93589de..c4b022ab8 100644 --- a/packages/turf-moran-index/README.md +++ b/packages/turf-moran-index/README.md @@ -2,6 +2,17 @@ +## MoranIndex + +Type: [object][1] + +### Properties + +* `moranIndex` **[number][2]** the moran's Index of the observed feature set +* `expectedMoranIndex` **[number][2]** the moran's Index of the random distribution +* `stdNorm` **[number][2]** the standard devitaion of the random distribution +* `zNorm` **[number][2]** the z-score of the observe samples with regard to the random distribution + ## moranIndex Moran's I measures patterns of attribute values associated with features. @@ -20,22 +31,22 @@ the z-score can be calculated based on a normal or random assumption. **Bibliography**\* -1. [Moran's I][1] +1. [Moran's I][3] -2. [pysal][2] +2. [pysal][4] 3. Andy Mitchell, The ESRI Guide to GIS Analysis Volume 2: Spatial Measurements & Statistics. ### Parameters -* `fc` **[FeatureCollection][3]\** -* `options` **[Object][4]** +* `fc` **[FeatureCollection][5]\** +* `options` **[Object][1]** - * `options.inputField` **[string][5]** the property name, must contain numeric values - * `options.threshold` **[number][6]** the distance threshold (optional, default `100000`) - * `options.p` **[number][6]** the Minkowski p-norm distance parameter (optional, default `2`) + * `options.inputField` **[string][6]** the property name, must contain numeric values + * `options.threshold` **[number][2]** the distance threshold (optional, default `100000`) + * `options.p` **[number][2]** the Minkowski p-norm distance parameter (optional, default `2`) * `options.binary` **[boolean][7]** whether transfrom the distance to binary (optional, default `false`) - * `options.alpha` **[number][6]** the distance decay parameter (optional, default `-1`) + * `options.alpha` **[number][2]** the distance decay parameter (optional, default `-1`) * `options.standardization` **[boolean][7]** wheter row standardization the distance (optional, default `true`) ### Examples @@ -51,55 +62,22 @@ const result = turf.moranIndex(dataset, { Returns **[MoranIndex][8]** -## mean +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -get mean of a list +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -### Parameters +[3]: https://en.wikipedia.org/wiki/Moran%27s_I -* `y` **[Array][9]<[number][6]>** +[4]: http://pysal.readthedocs.io/en/latest/index.html -Returns **[number][6]** +[5]: https://tools.ietf.org/html/rfc7946#section-3.3 -## variance - -get variance of a list - -### Parameters - -* `y` **[Array][9]<[number][6]>** - -Returns **[number][6]** - -## MoranIndex - -Type: [Object][4] - -### Properties - -* `moranIndex` **[number][6]** the moran's Index of the observed feature set -* `expectedMoranIndex` **[number][6]** the moran's Index of the random distribution -* `stdNorm` **[number][6]** the standard devitaion of the random distribution -* `zNorm` **[number][6]** the z-score of the observe samples with regard to the random distribution - -[1]: https://en.wikipedia.org/wiki/Moran%27s_I - -[2]: http://pysal.readthedocs.io/en/latest/index.html - -[3]: https://tools.ietf.org/html/rfc7946#section-3.3 - -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object - -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String - -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [8]: #moranindex -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array - --- diff --git a/packages/turf-moran-index/index.ts b/packages/turf-moran-index/index.ts index 362c35578..83a5e9e5b 100644 --- a/packages/turf-moran-index/index.ts +++ b/packages/turf-moran-index/index.ts @@ -2,6 +2,20 @@ import { FeatureCollection } from "geojson"; import { distanceWeight as spatialWeight } from "@turf/distance-weight"; import { featureEach } from "@turf/meta"; +/** + * @typedef {object} MoranIndex + * @property {number} moranIndex the moran's Index of the observed feature set + * @property {number} expectedMoranIndex the moran's Index of the random distribution + * @property {number} stdNorm the standard devitaion of the random distribution + * @property {number} zNorm the z-score of the observe samples with regard to the random distribution + */ +type MoranIndex = { + moranIndex: number; + expectedMoranIndex: number; + stdNorm: number; + zNorm: number; +}; + /** * Moran's I measures patterns of attribute values associated with features. * The method reveal whether similar values tend to occur near each other, @@ -25,7 +39,7 @@ import { featureEach } from "@turf/meta"; * * 3. Andy Mitchell, The ESRI Guide to GIS Analysis Volume 2: Spatial Measurements & Statistics. * - * @name moranIndex + * @function * @param {FeatureCollection} fc * @param {Object} options * @param {string} options.inputField the property name, must contain numeric values @@ -55,12 +69,7 @@ function moranIndex( alpha?: number; standardization?: boolean; } -): { - moranIndex: number; - expectedMoranIndex: number; - stdNorm: number; - zNorm: number; -} { +): MoranIndex { const inputField = options.inputField; const threshold = options.threshold || 100000; const p = options.p || 2; @@ -121,6 +130,8 @@ function moranIndex( /** * get mean of a list + * + * @private * @param {number[]} y * @returns {number} * @@ -134,6 +145,8 @@ function mean(y: number[]): number { } /** * get variance of a list + * + * @private * @param {number[]} y * @returns {number} * @@ -147,13 +160,5 @@ function variance(y: number[]): number { return sum / y.length; } -/** - * @typedef {Object} MoranIndex - * @property {number} moranIndex the moran's Index of the observed feature set - * @property {number} expectedMoranIndex the moran's Index of the random distribution - * @property {number} stdNorm the standard devitaion of the random distribution - * @property {number} zNorm the z-score of the observe samples with regard to the random distribution - */ - -export { moranIndex }; +export { moranIndex, MoranIndex }; export default moranIndex; diff --git a/packages/turf-nearest-neighbor-analysis/README.md b/packages/turf-nearest-neighbor-analysis/README.md index 5b66701df..0536682bd 100644 --- a/packages/turf-nearest-neighbor-analysis/README.md +++ b/packages/turf-nearest-neighbor-analysis/README.md @@ -2,16 +2,42 @@ +## NearestNeighborStatistics + +Nearest neighbour statistics. + +Type: [object][1] + +### Properties + +* `arealUnits` **[string][2]** +* `observedMeanDistance` **[number][3]** +* `expectedMeanDistance` **[number][3]** +* `numberOfPoints` **[number][3]** +* `zScore` **[number][3]** + +## NearestNeighborStudyArea + +Nearest neighbour study area polygon feature. + +Type: [object][1] + +### Properties + +* `properties` **[GeoJsonProperties][4]** + + * `properties.nearestNeighborAnalysis` **[NearestNeighborStatistics][5]** + ## nearestNeighborAnalysis Nearest Neighbor Analysis calculates an index based the average distances between points in the dataset, thereby providing inference as to whether the data is clustered, dispersed, or randomly distributed within the study area. -It returns a [Feature\][1] of the study area, with the results of +It returns a [Feature][4]<[Polygon][6]> of the study area, with the results of the analysis attached as part of of the `nearestNeighborAnalysis` property of the study area's `properties`. The attached -[*z*-score][2] indicates how many +[*z*-score][7] indicates how many standard deviations above or below the expected mean distance the data's observed mean distance is. The more negative, the more clustered. The more positive, the more evenly dispersed. A *z*-score between -2 and 2 indicates @@ -21,11 +47,11 @@ dispersed. **Remarks** -* Though the analysis will work on any [FeatureCollection][3] type, it - works best with [Point][4] collections. +* Though the analysis will work on any [FeatureCollection][8] type, it + works best with [Point][9] collections. * This analysis is *very* sensitive to the study area provided. - If no [Feature\][1] is passed as the study area, the function draws a box + If no [Feature][4]<[Polygon][6]> is passed as the study area, the function draws a box around the data, which may distort the findings. This analysis works best with a bounded area of interest within with the data is either clustered, dispersed, or randomly distributed. For example, a city's subway stops may @@ -37,16 +63,15 @@ dispersed. Philip J. Clark and Francis C. Evans, “Distance to Nearest Neighbor as a Measure of Spatial Relationships in Populations,” *Ecology* 35, no. 4 -(1954): 445–453, doi:[10.2307/1931034][5]. +(1954): 445–453, doi:[10.2307/1931034][10]. ### Parameters -* `dataset` **[FeatureCollection][3]\** FeatureCollection (pref. of points) to study -* `options` **[Object][6]** Optional parameters (optional, default `{}`) +* `dataset` **[FeatureCollection][8]\** FeatureCollection (pref. of points) to study +* `options` **[Object][1]** Optional parameters (optional, default `{}`) - * `options.studyArea` **[Feature][7]<[Polygon][8]>?** polygon representing the study area - * `options.units` **[string][9]** unit of measurement for distances and, squared, area. (optional, default `'kilometers'`) - * `options.properties` **[Object][6]** properties (optional, default `{}`) + * `options.studyArea` **[Feature][4]<[Polygon][6]>?** polygon representing the study area + * `options.properties` **[GeoJsonProperties][4]** properties (optional, default `{}`) ### Examples @@ -59,25 +84,29 @@ var nearestNeighborStudyArea = turf.nearestNeighborAnalysis(dataset); var addToMap = [dataset, nearestNeighborStudyArea]; ``` -Returns **[Feature][7]<[Polygon][8]>** A polygon of the study area or an approximation of one. +Returns **[NearestNeighborStudyArea][11]** A polygon of the study area or an approximation of one. + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[1]: Feature +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[2]: https://en.wikipedia.org/wiki/Standard_score +[4]: https://tools.ietf.org/html/rfc7946#section-3.2 -[3]: https://tools.ietf.org/html/rfc7946#section-3.3 +[5]: #nearestneighborstatistics -[4]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[6]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[5]: http://doi.org/10.2307/1931034 +[7]: https://en.wikipedia.org/wiki/Standard_score -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[8]: https://tools.ietf.org/html/rfc7946#section-3.3 -[7]: https://tools.ietf.org/html/rfc7946#section-3.2 +[9]: https://tools.ietf.org/html/rfc7946#section-3.1.2 -[8]: https://tools.ietf.org/html/rfc7946#section-3.1.6 +[10]: http://doi.org/10.2307/1931034 -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[11]: #nearestneighborstudyarea diff --git a/packages/turf-nearest-neighbor-analysis/index.ts b/packages/turf-nearest-neighbor-analysis/index.ts index 274ecb8ac..fbde954cc 100644 --- a/packages/turf-nearest-neighbor-analysis/index.ts +++ b/packages/turf-nearest-neighbor-analysis/index.ts @@ -19,6 +19,17 @@ import { AreaUnits, } from "@turf/helpers"; +/** + * Nearest neighbour statistics. + * + * @typedef {object} NearestNeighborStatistics + * @property {(Units & AreaUnits)} units + * @property {string} arealUnits + * @property {number} observedMeanDistance + * @property {number} expectedMeanDistance + * @property {number} numberOfPoints + * @property {number} zScore + */ interface NearestNeighborStatistics { units: Units & AreaUnits; arealUnits: string; @@ -28,6 +39,14 @@ interface NearestNeighborStatistics { zScore: number; } +/** + * Nearest neighbour study area polygon feature. + * + * @typedef {object} NearestNeighborStudyArea + * @extends Feature + * @property {GeoJsonProperties} properties + * @property {NearestNeighborStatistics} properties.nearestNeighborAnalysis + */ interface NearestNeighborStudyArea extends Feature { properties: { nearestNeighborAnalysis: NearestNeighborStatistics; @@ -40,7 +59,7 @@ interface NearestNeighborStudyArea extends Feature { * between points in the dataset, thereby providing inference as to whether the * data is clustered, dispersed, or randomly distributed within the study area. * - * It returns a {@link Feature} of the study area, with the results of + * It returns a {@link Feature}<{@link Polygon}> of the study area, with the results of * the analysis attached as part of of the `nearestNeighborAnalysis` property * of the study area's `properties`. The attached * [_z_-score](https://en.wikipedia.org/wiki/Standard_score) indicates how many @@ -57,7 +76,7 @@ interface NearestNeighborStudyArea extends Feature { * works best with {@link Point} collections. * * - This analysis is _very_ sensitive to the study area provided. - * If no {@link Feature} is passed as the study area, the function draws a box + * If no {@link Feature}<{@link Polygon}> is passed as the study area, the function draws a box * around the data, which may distort the findings. This analysis works best * with a bounded area of interest within with the data is either clustered, * dispersed, or randomly distributed. For example, a city's subway stops may @@ -71,13 +90,13 @@ interface NearestNeighborStudyArea extends Feature { * Measure of Spatial Relationships in Populations,” _Ecology_ 35, no. 4 * (1954): 445–453, doi:[10.2307/1931034](http://doi.org/10.2307/1931034). * - * @name nearestNeighborAnalysis + * @function * @param {FeatureCollection} dataset FeatureCollection (pref. of points) to study * @param {Object} [options={}] Optional parameters * @param {Feature} [options.studyArea] polygon representing the study area - * @param {string} [options.units='kilometers'] unit of measurement for distances and, squared, area. - * @param {Object} [options.properties={}] properties - * @returns {Feature} A polygon of the study area or an approximation of one. + * @param {Units & AreaUnits} [options.units='kilometers'] unit of measurement for distances and, squared, area. + * @param {GeoJsonProperties} [options.properties={}] properties + * @returns {NearestNeighborStudyArea} A polygon of the study area or an approximation of one. * @example * var bbox = [-65, 40, -63, 42]; * var dataset = turf.randomPoint(100, { bbox: bbox }); diff --git a/packages/turf-nearest-point-on-line/index.ts b/packages/turf-nearest-point-on-line/index.ts index 60f1ad078..1b75bd172 100644 --- a/packages/turf-nearest-point-on-line/index.ts +++ b/packages/turf-nearest-point-on-line/index.ts @@ -13,7 +13,7 @@ import { getCoord, getCoords } from "@turf/invariant"; /** * Returns the nearest point on a line to a given point. * - * @name nearestPointOnLine + * @function * @param {Geometry|Feature} lines lines to snap to * @param {Geometry|Feature|number[]} pt point to snap from * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-nearest-point-to-line/README.md b/packages/turf-nearest-point-to-line/README.md index 579691041..235543746 100644 --- a/packages/turf-nearest-point-to-line/README.md +++ b/packages/turf-nearest-point-to-line/README.md @@ -11,7 +11,7 @@ to a [line][3]. The returned point has a `dist` property indicating its distance * `points` **([FeatureCollection][2] | [GeometryCollection][4]<[Point][1]>)** Point Collection * `line` **([Feature][5] | [Geometry][6]<[LineString][3]>)** Line Feature -* `options` **[Object][7]?** Optional parameters +* `options` **[Object][7]?** Optional parameters (optional, default `{}`) * `options.units` **[string][8]** unit of the output distance property (eg: degrees, radians, miles, or kilometers) (optional, default `'kilometers'`) @@ -33,14 +33,6 @@ var addToMap = [nearest, line]; Returns **[Feature][5]<[Point][1]>** the closest point -## pt - -Translate Properties to final Point, priorities: - -1. options.properties -2. inherent Point properties -3. dist custom properties created by NearestPointToLine - [1]: https://tools.ietf.org/html/rfc7946#section-3.1.2 [2]: https://tools.ietf.org/html/rfc7946#section-3.3 diff --git a/packages/turf-nearest-point-to-line/index.ts b/packages/turf-nearest-point-to-line/index.ts index d0f61501b..8b647218c 100644 --- a/packages/turf-nearest-point-to-line/index.ts +++ b/packages/turf-nearest-point-to-line/index.ts @@ -15,7 +15,7 @@ import { pointToLineDistance } from "@turf/point-to-line-distance"; * Returns the closest {@link Point|point}, of a {@link FeatureCollection|collection} of points, * to a {@link LineString|line}. The returned point has a `dist` property indicating its distance to the line. * - * @name nearestPointToLine + * @function * @param {FeatureCollection|GeometryCollection} points Point Collection * @param {Feature|Geometry} line Line Feature * @param {Object} [options] Optional parameters @@ -71,7 +71,7 @@ function nearestPointToLine

( pt = point; } }); - /** + /* * Translate Properties to final Point, priorities: * 1. options.properties * 2. inherent Point properties diff --git a/packages/turf-nearest-point/index.ts b/packages/turf-nearest-point/index.ts index d53b5a8c9..7d2fa0e49 100644 --- a/packages/turf-nearest-point/index.ts +++ b/packages/turf-nearest-point/index.ts @@ -18,7 +18,7 @@ interface NearestPoint extends Feature { * point from the FeatureCollection closest to the reference. This calculation * is geodesic. * - * @name nearestPoint + * @function * @param {Coord} targetPoint the reference point * @param {FeatureCollection} points against input point set * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-planepoint/index.ts b/packages/turf-planepoint/index.ts index 9e6e53172..f54d0552f 100644 --- a/packages/turf-planepoint/index.ts +++ b/packages/turf-planepoint/index.ts @@ -11,7 +11,7 @@ import { Coord } from "@turf/helpers"; * of each triangle point can be provided by their respective 3rd coordinate * if their values are not provided as properties. * - * @name planepoint + * @function * @param {Coord} point the Point for which a z-value will be calculated * @param {Feature} triangle a Polygon feature with three vertices * @returns {number} the z-value for `interpolatedPoint` diff --git a/packages/turf-point-grid/index.ts b/packages/turf-point-grid/index.ts index 408f47b64..a577d2dc2 100644 --- a/packages/turf-point-grid/index.ts +++ b/packages/turf-point-grid/index.ts @@ -14,7 +14,7 @@ import { point, featureCollection, Units } from "@turf/helpers"; /** * Creates a grid of points * - * @name pointGrid + * @function * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order * @param {number} cellSide the distance between points * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-point-on-feature/index.ts b/packages/turf-point-on-feature/index.ts index 004cd5e8d..9c823f809 100644 --- a/packages/turf-point-on-feature/index.ts +++ b/packages/turf-point-on-feature/index.ts @@ -13,7 +13,7 @@ import { featureCollection, feature, point } from "@turf/helpers"; * * Given a {@link LineString}, the point will be along the string * * Given a {@link Point}, the point will the same as the input * - * @name pointOnFeature + * @function * @param {GeoJSON} geojson any Feature or FeatureCollection * @returns {Feature} a point on the surface of `input` * @example diff --git a/packages/turf-point-to-line-distance/index.ts b/packages/turf-point-to-line-distance/index.ts index 9b77f5895..bb97eaf7b 100644 --- a/packages/turf-point-to-line-distance/index.ts +++ b/packages/turf-point-to-line-distance/index.ts @@ -17,7 +17,7 @@ import { rhumbDistance } from "@turf/rhumb-distance"; * Calculates the distance between a given point and the nearest point on a * line. Sometimes referred to as the cross track distance. * - * @name pointToLineDistance + * @function * @param {Feature|Array} pt Feature or Geometry * @param {Feature} line GeoJSON Feature or Geometry * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-points-within-polygon/index.ts b/packages/turf-points-within-polygon/index.ts index 05c6d66b7..6679457b0 100644 --- a/packages/turf-points-within-polygon/index.ts +++ b/packages/turf-points-within-polygon/index.ts @@ -15,7 +15,7 @@ import { geomEach, featureEach, coordEach } from "@turf/meta"; /** * Finds {@link Points} or {@link MultiPoint} coordinate positions that fall within {@link (Multi)Polygon(s)}. * - * @name pointsWithinPolygon + * @function * @param {Feature|FeatureCollection} points Point(s) or MultiPoint(s) as input search * @param {FeatureCollection|Geometry|Feature} polygons (Multi)Polygon(s) to check if points are within * @returns {FeatureCollection} Point(s) or MultiPoint(s) with positions that land within at least one polygon. The geometry type will match what was passsed in diff --git a/packages/turf-polygon-smooth/index.ts b/packages/turf-polygon-smooth/index.ts index 9f8003e84..c74991eac 100644 --- a/packages/turf-polygon-smooth/index.ts +++ b/packages/turf-polygon-smooth/index.ts @@ -12,7 +12,7 @@ import { coordEach, geomEach } from "@turf/meta"; * Smooths a {@link Polygon} or {@link MultiPolygon}. Based on [Chaikin's algorithm](http://graphics.cs.ucdavis.edu/education/CAGDNotes/Chaikins-Algorithm/Chaikins-Algorithm.html). * Warning: may create degenerate polygons. * - * @name polygonSmooth + * @function * @param {FeatureCollection|Feature|Polygon|MultiPolygon} inputPolys (Multi)Polygon(s) to smooth * @param {Object} [options={}] Optional parameters * @param {string} [options.iterations=1] The number of times to smooth the polygon. A higher value means a smoother polygon. diff --git a/packages/turf-polygon-tangents/index.ts b/packages/turf-polygon-tangents/index.ts index 32b7a8665..7e27783ca 100644 --- a/packages/turf-polygon-tangents/index.ts +++ b/packages/turf-polygon-tangents/index.ts @@ -16,7 +16,7 @@ import { nearestPoint } from "@turf/nearest-point"; /** * Finds the tangents of a {@link Polygon|(Multi)Polygon} from a {@link Point}. * - * @name polygonTangents + * @function * @param {Coord} pt to calculate the tangent points from * @param {Feature} polygon to get tangents from * @returns {FeatureCollection} Feature Collection containing the two tangent points diff --git a/packages/turf-polygon-to-line/index.ts b/packages/turf-polygon-to-line/index.ts index fb9b07845..618e6187e 100644 --- a/packages/turf-polygon-to-line/index.ts +++ b/packages/turf-polygon-to-line/index.ts @@ -14,7 +14,7 @@ import { getGeom } from "@turf/invariant"; * Converts a {@link Polygon} to {@link LineString|(Multi)LineString} or {@link MultiPolygon} to a * {@link FeatureCollection} of {@link LineString|(Multi)LineString}. * - * @name polygonToLine + * @function * @param {Feature} poly Feature to convert * @param {Object} [options={}] Optional parameters * @param {Object} [options.properties={}] translates GeoJSON properties to Feature diff --git a/packages/turf-polygonize/index.ts b/packages/turf-polygonize/index.ts index 30f4e7529..ae3f007ea 100644 --- a/packages/turf-polygonize/index.ts +++ b/packages/turf-polygonize/index.ts @@ -22,7 +22,7 @@ import { EdgeRing } from "./lib/EdgeRing.js"; * - Dangles: edges which have one or both ends which are not incident on another edge endpoint. * - Cut Edges (bridges): edges that are connected at both ends but which do not form part of a polygon. * - * @name polygonize + * @function * @param {FeatureCollection|Geometry|Feature} geoJson Lines in order to polygonize * @returns {FeatureCollection} Polygons created * @throws {Error} if geoJson is invalid. diff --git a/packages/turf-projection/README.md b/packages/turf-projection/README.md index 1c5985895..c6cd94327 100644 --- a/packages/turf-projection/README.md +++ b/packages/turf-projection/README.md @@ -9,7 +9,7 @@ Converts a WGS84 GeoJSON object into Mercator (EPSG:900913) projection ### Parameters * `geojson` **([GeoJSON][1] | [Position][2])** WGS84 GeoJSON object -* `options` **[Object][3]?** Optional parameters +* `options` **[Object][3]?** Optional parameters (optional, default `{}`) * `options.mutate` **[boolean][4]** allows GeoJSON input to be mutated (significant performance increase if true) (optional, default `false`) @@ -32,7 +32,7 @@ Converts a Mercator (EPSG:900913) GeoJSON object into WGS84 projection ### Parameters * `geojson` **([GeoJSON][1] | [Position][2])** Mercator GeoJSON object -* `options` **[Object][3]?** Optional parameters +* `options` **[Object][3]?** Optional parameters (optional, default `{}`) * `options.mutate` **[boolean][4]** allows GeoJSON input to be mutated (significant performance increase if true) (optional, default `false`) diff --git a/packages/turf-projection/index.ts b/packages/turf-projection/index.ts index d9f9bd3a8..232ff0c99 100644 --- a/packages/turf-projection/index.ts +++ b/packages/turf-projection/index.ts @@ -6,7 +6,7 @@ import { clone } from "@turf/clone"; /** * Converts a WGS84 GeoJSON object into Mercator (EPSG:900913) projection * - * @name toMercator + * @function * @param {GeoJSON|Position} geojson WGS84 GeoJSON object * @param {Object} [options] Optional parameters * @param {boolean} [options.mutate=false] allows GeoJSON input to be mutated (significant performance increase if true) @@ -28,7 +28,7 @@ function toMercator( /** * Converts a Mercator (EPSG:900913) GeoJSON object into WGS84 projection * - * @name toWgs84 + * @function * @param {GeoJSON|Position} geojson Mercator GeoJSON object * @param {Object} [options] Optional parameters * @param {boolean} [options.mutate=false] allows GeoJSON input to be mutated (significant performance increase if true) diff --git a/packages/turf-quadrat-analysis/README.md b/packages/turf-quadrat-analysis/README.md index d4802e36e..a3486f854 100644 --- a/packages/turf-quadrat-analysis/README.md +++ b/packages/turf-quadrat-analysis/README.md @@ -34,8 +34,8 @@ which is simply the area of the study area divided by the number of features. * `pointFeatureSet` **[FeatureCollection][1]<[Point][2]>** point set to study * `options` **[Object][3]** optional parameters (optional, default `{}`) - * `options.studyBbox` **bbox?** bbox representing the study area - * `options.confidenceLevel` **[number][4]** a confidence level. + * `options.studyBbox` **\[[number][4], [number][4], [number][4], [number][4]]?** bbox representing the study area + * `options.confidenceLevel` **(`20` | `15` | `10` | `5` | `2` | `1`)** a confidence level. The unit is percentage . 5 means 95%, value must be in [K\_TABLE][5] (optional, default `20`) ### Examples @@ -46,7 +46,7 @@ var dataset = turf.randomPoint(100, { bbox: bbox }); var result = turf.quadratAnalysis(dataset); ``` -Returns **[Object][3]** result [QuadratAnalysisResult][6] +Returns **[QuadratAnalysisResult][6]** result ## K\_TABLE @@ -56,18 +56,18 @@ Type: [Object][3] ### Properties -* `20` **[number][4]** -* `15` **[number][4]** -* `10` **[number][4]** -* `5` **[number][4]** -* `2` **[number][4]** -* `1` **[number][4]** +* `20` **[number][4]** 1.07275 +* `15` **[number][4]** 1.13795 +* `10` **[number][4]** 1.22385 +* `5` **[number][4]** 1.3581 +* `2` **[number][4]** 1.51743 +* `1` **[number][4]** 1.62762 ## QuadratAnalysisResult the return type of the quadratAnalysis -Type: [Object][3] +Type: [object][3] ### Properties diff --git a/packages/turf-quadrat-analysis/index.ts b/packages/turf-quadrat-analysis/index.ts index e3c98701c..984493402 100644 --- a/packages/turf-quadrat-analysis/index.ts +++ b/packages/turf-quadrat-analysis/index.ts @@ -39,13 +39,13 @@ interface QuadratAnalysisResult { * which is simply the area of the study area divided by the number of features. * * - * @name quadratAnalysis + * @function * @param {FeatureCollection} pointFeatureSet point set to study * @param {Object} [options={}] optional parameters - * @param {bbox} [options.studyBbox] bbox representing the study area - * @param {number} [options.confidenceLevel=20] a confidence level. + * @param {[number, number, number, number]} [options.studyBbox] bbox representing the study area + * @param {20 | 15 | 10 | 5 | 2 | 1} [options.confidenceLevel=20] a confidence level. * The unit is percentage . 5 means 95%, value must be in {@link K_TABLE} - * @returns {Object} result {@link QuadratAnalysisResult} + * @returns {QuadratAnalysisResult} result * @example * * var bbox = [-65, 40, -63, 42]; @@ -160,13 +160,15 @@ function quadratAnalysis( /** * the confidence level - * @type {Object} K_TABLE - * @property {number} 20 - * @property {number} 15 - * @property {number} 10 - * @property {number} 5 - * @property {number} 2 - * @property {number} 1 + * + * @constant + * @type {Object} + * @property {number} 20 1.07275 + * @property {number} 15 1.13795 + * @property {number} 10 1.22385 + * @property {number} 5 1.3581 + * @property {number} 2 1.51743 + * @property {number} 1 1.62762 */ const K_TABLE = { 20: 1.07275, @@ -179,11 +181,12 @@ const K_TABLE = { /** * the return type of the quadratAnalysis - * @typedef {Object} QuadratAnalysisResult + * + * @typedef {object} QuadratAnalysisResult * @property {number} criticalValue * @property {number} maxAbsoluteDifference * @property {boolean} isRandom - * @property {Array.} observedDistribution the cumulative distribution of observed features, + * @property {Array} observedDistribution the cumulative distribution of observed features, * the index represents the number of features in the quadrat. */ diff --git a/packages/turf-random/README.md b/packages/turf-random/README.md index 53af241fe..eb715a24c 100644 --- a/packages/turf-random/README.md +++ b/packages/turf-random/README.md @@ -4,11 +4,11 @@ ## randomPosition -Returns a random position within a [box][1]. +Returns a random position within a [bounding box][1]. ### Parameters -* `bbox` **[Array][2]<[number][3]>** a bounding box inside of which positions are placed. (optional, default `[-180,-90,180,90]`) +* `bbox` **[BBox][1]** a bounding box inside of which positions are placed. (optional, default `[-180,-90,180,90]`) ### Examples @@ -17,20 +17,20 @@ var position = turf.randomPosition([-180, -90, 180, 90]) // => position ``` -* Throws **[Error][4]** if bbox is invalid +* Throws **[Error][2]** if bbox is invalid -Returns **[Array][2]<[number][3]>** Position \[longitude, latitude] +Returns **[Position][3]** Position \[longitude, latitude] ## randomPoint -Returns a random [point][5]. +Returns a random [point][4]. ### Parameters -* `count` **[number][3]** how many geometries will be generated (optional, default `1`) +* `count` **[number][5]** how many geometries will be generated (optional, default `1`) * `options` **[Object][6]** Optional parameters (optional, default `{}`) - * `options.bbox` **[Array][2]<[number][3]>** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) + * `options.bbox` **[BBox][1]** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) ### Examples @@ -39,7 +39,7 @@ var points = turf.randomPoint(25, {bbox: [-180, -90, 180, 90]}) // => points ``` -* Throws **[Error][4]** if bbox is invalid +* Throws **[Error][2]** if bbox is invalid Returns **[FeatureCollection][7]<[Point][8]>** GeoJSON FeatureCollection of points @@ -49,12 +49,12 @@ Returns a random [polygon][9]. ### Parameters -* `count` **[number][3]** how many geometries will be generated (optional, default `1`) +* `count` **[number][5]** how many geometries will be generated (optional, default `1`) * `options` **[Object][6]** Optional parameters (optional, default `{}`) - * `options.bbox` **[Array][2]<[number][3]>** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) - * `options.num_vertices` **[number][3]** is how many coordinates each LineString will contain. (optional, default `10`) - * `options.max_radial_length` **[number][3]** is the maximum number of decimal degrees latitude or longitude that a + * `options.bbox` **[BBox][1]** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) + * `options.num_vertices` **[number][5]** is how many coordinates each LineString will contain. (optional, default `10`) + * `options.max_radial_length` **[number][5]** is the maximum number of decimal degrees latitude or longitude that a vertex can reach out of the center of the Polygon. (optional, default `10`) ### Examples @@ -64,24 +64,24 @@ var polygons = turf.randomPolygon(25, {bbox: [-180, -90, 180, 90]}) // => polygons ``` -* Throws **[Error][4]** if bbox is invalid +* Throws **[Error][2]** if bbox is invalid Returns **[FeatureCollection][7]<[Polygon][10]>** GeoJSON FeatureCollection of polygons ## randomLineString -Returns a random [linestring][11]. +Returns a random [LineString][11]. ### Parameters -* `count` **[number][3]** how many geometries will be generated (optional, default `1`) +* `count` **[number][5]** how many geometries will be generated (optional, default `1`) * `options` **[Object][6]** Optional parameters (optional, default `{}`) - * `options.bbox` **[Array][2]<[number][3]>** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) - * `options.num_vertices` **[number][3]** is how many coordinates each LineString will contain. (optional, default `10`) - * `options.max_length` **[number][3]** is the maximum number of decimal degrees that a + * `options.bbox` **[BBox][1]** a bounding box inside of which geometries are placed. (optional, default `[-180,-90,180,90]`) + * `options.num_vertices` **[number][5]** is how many coordinates each LineString will contain. (optional, default `10`) + * `options.max_length` **[number][5]** is the maximum number of decimal degrees that a vertex can be from its predecessor (optional, default `0.0001`) - * `options.max_rotation` **[number][3]** is the maximum number of radians that a + * `options.max_rotation` **[number][5]** is the maximum number of radians that a line segment can turn from the previous segment. (optional, default `Math.PI/8`) ### Examples @@ -91,19 +91,19 @@ var lineStrings = turf.randomLineString(25, {bbox: [-180, -90, 180, 90]}) // => lineStrings ``` -* Throws **[Error][4]** if bbox is invalid +* Throws **[Error][2]** if bbox is invalid -Returns **[FeatureCollection][7]<[LineString][12]>** GeoJSON FeatureCollection of linestrings +Returns **[FeatureCollection][7]<[LineString][11]>** GeoJSON FeatureCollection of linestrings -[1]: bounding +[1]: https://tools.ietf.org/html/rfc7946#section-5 -[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error -[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[3]: https://developer.mozilla.org/docs/Web/API/Position -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error +[4]: point -[5]: point +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number [6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object @@ -115,9 +115,7 @@ Returns **[FeatureCollection][7]<[LineString][12]>** GeoJSON FeatureCollection o [10]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[11]: linestring - -[12]: https://tools.ietf.org/html/rfc7946#section-3.1.4 +[11]: https://tools.ietf.org/html/rfc7946#section-3.1.4 diff --git a/packages/turf-random/index.ts b/packages/turf-random/index.ts index a52fddae6..f64391d46 100644 --- a/packages/turf-random/index.ts +++ b/packages/turf-random/index.ts @@ -17,11 +17,11 @@ import { } from "@turf/helpers"; /** - * Returns a random position within a {@link bounding box}. + * Returns a random position within a {@link BBox|bounding box}. * - * @name randomPosition - * @param {Array} [bbox=[-180, -90, 180, 90]] a bounding box inside of which positions are placed. - * @returns {Array} Position [longitude, latitude] + * @function + * @param {BBox} [bbox=[-180, -90, 180, 90]] a bounding box inside of which positions are placed. + * @returns {Position} Position [longitude, latitude] * @throws {Error} if bbox is invalid * @example * var position = turf.randomPosition([-180, -90, 180, 90]) @@ -56,10 +56,10 @@ function checkBBox(bbox?: BBox | { bbox: BBox }) { /** * Returns a random {@link point}. * - * @name randomPoint + * @function * @param {number} [count=1] how many geometries will be generated * @param {Object} [options={}] Optional parameters - * @param {Array} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. + * @param {BBox} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. * @returns {FeatureCollection} GeoJSON FeatureCollection of points * @throws {Error} if bbox is invalid * @example @@ -86,10 +86,10 @@ function randomPoint( /** * Returns a random {@link polygon}. * - * @name randomPolygon + * @function * @param {number} [count=1] how many geometries will be generated * @param {Object} [options={}] Optional parameters - * @param {Array} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. + * @param {BBox} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. * @param {number} [options.num_vertices=10] is how many coordinates each LineString will contain. * @param {number} [options.max_radial_length=10] is the maximum number of decimal degrees latitude or longitude that a * vertex can reach out of the center of the Polygon. @@ -174,12 +174,12 @@ function randomPolygon( } /** - * Returns a random {@link linestring}. + * Returns a random {@link LineString}. * - * @name randomLineString + * @function * @param {number} [count=1] how many geometries will be generated * @param {Object} [options={}] Optional parameters - * @param {Array} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. + * @param {BBox} [options.bbox=[-180, -90, 180, 90]] a bounding box inside of which geometries are placed. * @param {number} [options.num_vertices=10] is how many coordinates each LineString will contain. * @param {number} [options.max_length=0.0001] is the maximum number of decimal degrees that a * vertex can be from its predecessor diff --git a/packages/turf-rectangle-grid/index.ts b/packages/turf-rectangle-grid/index.ts index f8034dc14..15bbbfabb 100644 --- a/packages/turf-rectangle-grid/index.ts +++ b/packages/turf-rectangle-grid/index.ts @@ -16,7 +16,7 @@ import { /** * Creates a grid of rectangular polygons with width and height consistent in degrees * - * @name rectangleGrid + * @function * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. * @param {number} cellWidth width of each cell, in units * @param {number} cellHeight height of each cell, in units diff --git a/packages/turf-rewind/index.ts b/packages/turf-rewind/index.ts index f5a0226e9..4c7fffaee 100644 --- a/packages/turf-rewind/index.ts +++ b/packages/turf-rewind/index.ts @@ -19,7 +19,7 @@ import type { AllGeoJSON } from "@turf/helpers"; /** * Rewind {@link LineString|(Multi)LineString} or {@link Polygon|(Multi)Polygon} outer ring counterclockwise and inner rings clockwise (Uses {@link http://en.wikipedia.org/wiki/Shoelace_formula|Shoelace Formula}). * - * @name rewind + * @function * @param {GeoJSON} geojson input GeoJSON Polygon * @param {Object} [options={}] Optional parameters * @param {boolean} [options.reverse=false] enable reverse winding diff --git a/packages/turf-rhumb-bearing/README.md b/packages/turf-rhumb-bearing/README.md index a8be86d3f..c69464d9d 100644 --- a/packages/turf-rhumb-bearing/README.md +++ b/packages/turf-rhumb-bearing/README.md @@ -11,7 +11,7 @@ i.e. the angle measured in degrees start the north line (0 degrees) * `start` **[Coord][2]** starting Point * `end` **[Coord][2]** ending Point -* `options` **[Object][3]?** Optional parameters +* `options` **[Object][3]?** Optional parameters (optional, default `{}`) * `options.final` **[boolean][4]** calculates the final bearing if true (optional, default `false`) diff --git a/packages/turf-rhumb-bearing/index.ts b/packages/turf-rhumb-bearing/index.ts index 16372c398..c3d48ccc9 100644 --- a/packages/turf-rhumb-bearing/index.ts +++ b/packages/turf-rhumb-bearing/index.ts @@ -6,7 +6,7 @@ import { getCoord } from "@turf/invariant"; * Takes two {@link Point|points} and finds the bearing angle between them along a Rhumb line * i.e. the angle measured in degrees start the north line (0 degrees) * - * @name rhumbBearing + * @function * @param {Coord} start starting Point * @param {Coord} end ending Point * @param {Object} [options] Optional parameters diff --git a/packages/turf-rhumb-destination/index.ts b/packages/turf-rhumb-destination/index.ts index a91cdf8dd..17e0472f3 100644 --- a/packages/turf-rhumb-destination/index.ts +++ b/packages/turf-rhumb-destination/index.ts @@ -14,7 +14,7 @@ import { getCoord } from "@turf/invariant"; * Returns the destination {@link Point} having travelled the given distance along a Rhumb line from the * origin Point with the (varant) given bearing. * - * @name rhumbDestination + * @function * @param {Coord} origin starting point * @param {number} distance distance from the starting point * @param {number} bearing varant bearing angle ranging from -180 to 180 degrees from north diff --git a/packages/turf-rhumb-distance/README.md b/packages/turf-rhumb-distance/README.md index 17b630849..3dd3bf2e0 100644 --- a/packages/turf-rhumb-distance/README.md +++ b/packages/turf-rhumb-distance/README.md @@ -11,7 +11,7 @@ miles, or kilometers. * `from` **[Coord][2]** origin point * `to` **[Coord][2]** destination point -* `options` **[Object][3]?** Optional parameters +* `options` **[Object][3]?** Optional parameters (optional, default `{}`) * `options.units` **[string][4]** can be degrees, radians, miles, or kilometers (optional, default `"kilometers"`) diff --git a/packages/turf-rhumb-distance/index.ts b/packages/turf-rhumb-distance/index.ts index fe07ad145..37f7f0429 100644 --- a/packages/turf-rhumb-distance/index.ts +++ b/packages/turf-rhumb-distance/index.ts @@ -6,7 +6,7 @@ import { getCoord } from "@turf/invariant"; * Calculates the distance along a rhumb line between two {@link Point|points} in degrees, radians, * miles, or kilometers. * - * @name rhumbDistance + * @function * @param {Coord} from origin point * @param {Coord} to destination point * @param {Object} [options] Optional parameters diff --git a/packages/turf-sample/README.md b/packages/turf-sample/README.md index d853c8b2c..49079f834 100644 --- a/packages/turf-sample/README.md +++ b/packages/turf-sample/README.md @@ -8,8 +8,9 @@ Takes a [FeatureCollection][1] and returns a FeatureCollection with given number ### Parameters -* `featurecollection` **[FeatureCollection][1]** set of input features +* `fc` **[FeatureCollection][1]\** * `num` **[number][3]** number of features to select +* `featurecollection` **[FeatureCollection][1]** set of input features ### Examples diff --git a/packages/turf-sample/index.ts b/packages/turf-sample/index.ts index c3b7284ea..e96bbcaa2 100644 --- a/packages/turf-sample/index.ts +++ b/packages/turf-sample/index.ts @@ -5,7 +5,7 @@ import { featureCollection } from "@turf/helpers"; /** * Takes a {@link FeatureCollection} and returns a FeatureCollection with given number of {@link Feature|features} at random. * - * @name sample + * @function * @param {FeatureCollection} featurecollection set of input features * @param {number} num number of features to select * @returns {FeatureCollection} a FeatureCollection with `n` features diff --git a/packages/turf-sector/index.ts b/packages/turf-sector/index.ts index e648cfb4d..21755a4b3 100644 --- a/packages/turf-sector/index.ts +++ b/packages/turf-sector/index.ts @@ -9,7 +9,7 @@ import { getCoords } from "@turf/invariant"; * Creates a circular sector of a circle of given radius and center {@link Point}, * between (clockwise) bearing1 and bearing2; 0 bearing is North of center point, positive clockwise. * - * @name sector + * @function * @param {Coord} center center point * @param {number} radius radius of the circle * @param {number} bearing1 angle, in decimal degrees, of the first radius of the sector diff --git a/packages/turf-shortest-path/README.md b/packages/turf-shortest-path/README.md index 4875b1b76..567d6c9b1 100644 --- a/packages/turf-shortest-path/README.md +++ b/packages/turf-shortest-path/README.md @@ -5,17 +5,17 @@ ## shortestPath Returns the shortest [path][1] from [start][2] to [end][2] without colliding with -any [Feature][3] in [ obstacles][4] +any [Feature][3] in obstacles [FeatureCollection][4]<[Polygon][5]> ### Parameters -* `start` **[Coord][5]** point -* `end` **[Coord][5]** point -* `options` **[Object][6]** optional parameters (optional, default `{}`) +* `start` **[Coord][6]** point +* `end` **[Coord][6]** point +* `options` **[Object][7]** optional parameters (optional, default `{}`) - * `options.obstacles` **([Geometry][7] | [Feature][3] | [FeatureCollection][8]<[Polygon][9]>)?** areas which path cannot travel - * `options.units` **[string][10]** unit in which resolution & minimum distance will be expressed in; it can be degrees, radians, miles, kilometers, ... (optional, default `'kilometers'`) - * `options.resolution` **[number][11]** distance between matrix points on which the path will be calculated (optional, default `100`) + * `options.obstacles` **([Polygon][5] | [Feature][3]<[Polygon][5]> | [FeatureCollection][4]<[Polygon][5]>)?** areas which path cannot travel + * `options.units` **Units** unit in which resolution & minimum distance will be expressed in; it can be degrees, radians, miles, kilometers, ... (optional, default `'kilometers'`) + * `options.resolution` **[number][8]** distance between matrix points on which the path will be calculated (optional, default `100`) ### Examples @@ -23,7 +23,7 @@ any [Feature][3] in [ obstacles][4] var start = [-5, -6]; var end = [9, -6]; var options = { - obstacles: turf.polygon([[[0, -7], [5, -7], [5, -3], [0, -3], [0, -7]]]) + obstacles: turf.polygon([[[0, -7], [5, -7], [5, -3], [0, -3], [0, -7]]]).geometry }; var path = turf.shortestPath(start, end, options); @@ -40,21 +40,15 @@ Returns **[Feature][3]<[LineString][1]>** shortest path between start and end [3]: https://tools.ietf.org/html/rfc7946#section-3.2 -[4]: FeatureCollection +[4]: https://tools.ietf.org/html/rfc7946#section-3.3 -[5]: https://tools.ietf.org/html/rfc7946#section-3.1.1 +[5]: https://tools.ietf.org/html/rfc7946#section-3.1.6 -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[6]: https://tools.ietf.org/html/rfc7946#section-3.1.1 -[7]: https://tools.ietf.org/html/rfc7946#section-3.1 +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[8]: https://tools.ietf.org/html/rfc7946#section-3.3 - -[9]: https://tools.ietf.org/html/rfc7946#section-3.1.6 - -[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String - -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/packages/turf-shortest-path/index.ts b/packages/turf-shortest-path/index.ts index 33908b2c8..c1ad30a48 100644 --- a/packages/turf-shortest-path/index.ts +++ b/packages/turf-shortest-path/index.ts @@ -27,21 +27,21 @@ import { Graph, GridNode, astar } from "./lib/javascript-astar.js"; /** * Returns the shortest {@link LineString|path} from {@link Point|start} to {@link Point|end} without colliding with - * any {@link Feature} in {@link FeatureCollection| obstacles} + * any {@link Feature} in obstacles {@link FeatureCollection}<{@link Polygon}> * - * @name shortestPath + * @function * @param {Coord} start point * @param {Coord} end point * @param {Object} [options={}] optional parameters - * @param {Geometry|Feature|FeatureCollection} [options.obstacles] areas which path cannot travel - * @param {string} [options.units='kilometers'] unit in which resolution & minimum distance will be expressed in; it can be degrees, radians, miles, kilometers, ... + * @param {Polygon|Feature|FeatureCollection} [options.obstacles] areas which path cannot travel + * @param {Units} [options.units='kilometers'] unit in which resolution & minimum distance will be expressed in; it can be degrees, radians, miles, kilometers, ... * @param {number} [options.resolution=100] distance between matrix points on which the path will be calculated * @returns {Feature} shortest path between start and end * @example * var start = [-5, -6]; * var end = [9, -6]; * var options = { - * obstacles: turf.polygon([[[0, -7], [5, -7], [5, -3], [0, -3], [0, -7]]]) + * obstacles: turf.polygon([[[0, -7], [5, -7], [5, -3], [0, -3], [0, -7]]]).geometry * }; * * var path = turf.shortestPath(start, end, options); diff --git a/packages/turf-simplify/index.ts b/packages/turf-simplify/index.ts index ec2d26cd0..0556207ee 100644 --- a/packages/turf-simplify/index.ts +++ b/packages/turf-simplify/index.ts @@ -10,7 +10,7 @@ import { simplify as simplifyJS } from "./lib/simplify.js"; * [simplify-js](http://mourner.github.io/simplify-js/) to perform simplification using the Ramer-Douglas-Peucker algorithm. * * - * @name simplify + * @function * @param {GeoJSON} geojson object to be simplified * @param {Object} [options={}] Optional parameters * @param {number} [options.tolerance=1] simplification tolerance diff --git a/packages/turf-square-grid/index.ts b/packages/turf-square-grid/index.ts index 33a8a95e9..4cf2d1acc 100644 --- a/packages/turf-square-grid/index.ts +++ b/packages/turf-square-grid/index.ts @@ -12,7 +12,7 @@ import { rectangleGrid } from "@turf/rectangle-grid"; /** * Creates a grid of square polygons with cell length consistent in degrees * - * @name squareGrid + * @function * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order. If the grid does not fill the bbox perfectly, it is centered. * @param {number} cellSide length of each cell side. * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-square/index.ts b/packages/turf-square/index.ts index 1c477b528..7818261b9 100644 --- a/packages/turf-square/index.ts +++ b/packages/turf-square/index.ts @@ -5,7 +5,7 @@ import { BBox } from "geojson"; * Takes a bounding box and calculates the minimum square bounding box that * would contain the input. * - * @name square + * @function * @param {BBox} bbox extent in [west, south, east, north] order * @returns {BBox} a square surrounding `bbox` * @example diff --git a/packages/turf-standard-deviational-ellipse/index.ts b/packages/turf-standard-deviational-ellipse/index.ts index e73f4072e..a3c9204b5 100644 --- a/packages/turf-standard-deviational-ellipse/index.ts +++ b/packages/turf-standard-deviational-ellipse/index.ts @@ -50,7 +50,7 @@ declare interface StandardDeviationalEllipse extends Feature { * doi:{@link https://doi.org/10.1086/214336|10.1086/214336}. * * - * @name standardDeviationalEllipse + * @function * @param {FeatureCollection} points GeoJSON points * @param {Object} [options={}] Optional parameters * @param {string} [options.weight] the property name used to weight the center diff --git a/packages/turf-tag/index.ts b/packages/turf-tag/index.ts index 7c1d02917..2d1561c15 100644 --- a/packages/turf-tag/index.ts +++ b/packages/turf-tag/index.ts @@ -6,7 +6,7 @@ import { featureEach } from "@turf/meta"; /** * Takes a set of {@link Point|points} and a set of {@link Polygon|polygons} and/or {@link MultiPolygon|multipolygons} and performs a spatial join. * - * @name tag + * @function * @param {FeatureCollection} points input points * @param {FeatureCollection} polygons input (multi)polygons * @param {string} field property in `polygons` to add to joined {} features diff --git a/packages/turf-tesselate/index.ts b/packages/turf-tesselate/index.ts index 54ed91eaf..2bb01f0bd 100644 --- a/packages/turf-tesselate/index.ts +++ b/packages/turf-tesselate/index.ts @@ -12,7 +12,7 @@ import { polygon } from "@turf/helpers"; * Tesselates a polygon or multipolygon into a collection of triangle polygons * using [earcut](https://github.com/mapbox/earcut). * - * @name tesselate + * @function * @param {Feature} poly the polygon to tesselate * @returns {FeatureCollection} collection of polygon tesselations * @example diff --git a/packages/turf-tin/index.ts b/packages/turf-tin/index.ts index 1864d9e95..3843db9a1 100644 --- a/packages/turf-tin/index.ts +++ b/packages/turf-tin/index.ts @@ -24,7 +24,7 @@ interface Vertice { * and `c` representing its value at each of the points that represent the corners of the * triangle. * - * @name tin + * @function * @param {FeatureCollection} points input points * @param {String} [z] name of the property from which to pull z values * This is optional: if not given, then there will be no extra data added to the derived triangles. diff --git a/packages/turf-transform-rotate/index.ts b/packages/turf-transform-rotate/index.ts index 4d8216a82..9445b666f 100644 --- a/packages/turf-transform-rotate/index.ts +++ b/packages/turf-transform-rotate/index.ts @@ -11,7 +11,7 @@ import { isObject, Coord } from "@turf/helpers"; /** * Rotates any geojson Feature or Geometry of a specified angle, around its `centroid` or a given `pivot` point. * - * @name transformRotate + * @function * @param {GeoJSON} geojson object to be rotated * @param {number} angle of rotation in decimal degrees, positive clockwise * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-transform-scale/index.ts b/packages/turf-transform-scale/index.ts index 7a09eb05a..583352060 100644 --- a/packages/turf-transform-scale/index.ts +++ b/packages/turf-transform-scale/index.ts @@ -17,7 +17,7 @@ import { getCoord, getCoords, getType } from "@turf/invariant"; * If a FeatureCollection is provided, the origin point will be calculated * based on each individual feature _unless_ an exact * - * @name transformScale + * @function * @param {GeoJSON|GeometryCollection} geojson objects to be scaled * @param {number} factor of scaling, positive values greater than 0. Numbers between 0 and 1 will shrink the geojson, numbers greater than 1 will expand it, a factor of 1 will not change the geojson. * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-transform-translate/index.ts b/packages/turf-transform-translate/index.ts index 696c28906..ef20f1613 100644 --- a/packages/turf-transform-translate/index.ts +++ b/packages/turf-transform-translate/index.ts @@ -9,7 +9,7 @@ import { rhumbDestination } from "@turf/rhumb-destination"; * Moves any geojson Feature or Geometry of a specified distance along a Rhumb Line * on the provided direction angle. * - * @name transformTranslate + * @function * @param {GeoJSON|GeometryCollection} geojson object to be translated * @param {number} distance length of the motion; negative values determine motion in opposite direction * @param {number} direction of the motion; angle from North in decimal degrees, positive clockwise diff --git a/packages/turf-triangle-grid/index.ts b/packages/turf-triangle-grid/index.ts index fc0f7b3f2..cf11f2b49 100644 --- a/packages/turf-triangle-grid/index.ts +++ b/packages/turf-triangle-grid/index.ts @@ -12,7 +12,7 @@ import { polygon, featureCollection, Units } from "@turf/helpers"; /** * Creates a grid of triangular polygons. * - * @name triangleGrid + * @function * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order * @param {number} cellSide dimension of each grid cell. Two triangles are created in each cell. * @param {Object} [options={}] Optional parameters diff --git a/packages/turf-truncate/index.ts b/packages/turf-truncate/index.ts index 699a3ce69..fba1490ff 100644 --- a/packages/turf-truncate/index.ts +++ b/packages/turf-truncate/index.ts @@ -4,7 +4,7 @@ import { AllGeoJSON, isObject } from "@turf/helpers"; /** * Takes a GeoJSON Feature or FeatureCollection and truncates the precision of the geometry. * - * @name truncate + * @function * @param {GeoJSON} geojson any GeoJSON Feature, FeatureCollection, Geometry or GeometryCollection. * @param {Object} [options={}] Optional parameters * @param {number} [options.precision=6] coordinate decimal precision diff --git a/packages/turf-union/README.md b/packages/turf-union/README.md index 42f68d484..64b85b567 100644 --- a/packages/turf-union/README.md +++ b/packages/turf-union/README.md @@ -8,10 +8,11 @@ Takes input [(Multi)Polygon(s)][1] and returns a combined polygon. If the input ### Parameters -* `polygon1` **[Feature][3]<([Polygon][1] | [MultiPolygon][2])>** input Polygon features +* `features` **[FeatureCollection][3]<([Polygon][1] | [MultiPolygon][2])>** * `options` **[Object][4]** Optional Parameters (optional, default `{}`) * `options.properties` **[Object][4]** Translate Properties to output Feature (optional, default `{}`) +* `polygon1` **[Feature][5]<([Polygon][1] | [MultiPolygon][2])>** input Polygon features ### Examples @@ -37,16 +38,18 @@ var union = turf.union(turf.featureCollection([poly1, poly2])); var addToMap = [poly1, poly2, union]; ``` -Returns **[Feature][3]<([Polygon][1] | [MultiPolygon][2])>** a combined [Polygon][1] or [MultiPolygon][2] feature, or null if the inputs are empty +Returns **[Feature][5]<([Polygon][1] | [MultiPolygon][2])>** a combined [Polygon][1] or [MultiPolygon][2] feature, or null if the inputs are empty [1]: https://tools.ietf.org/html/rfc7946#section-3.1.6 [2]: https://tools.ietf.org/html/rfc7946#section-3.1.7 -[3]: https://tools.ietf.org/html/rfc7946#section-3.2 +[3]: https://tools.ietf.org/html/rfc7946#section-3.3 [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[5]: https://tools.ietf.org/html/rfc7946#section-3.2 + --- diff --git a/packages/turf-union/index.ts b/packages/turf-union/index.ts index 9db47ad20..4c0b6d662 100644 --- a/packages/turf-union/index.ts +++ b/packages/turf-union/index.ts @@ -12,7 +12,7 @@ import { /** * Takes input {@link (Multi)Polygon(s)} and returns a combined polygon. If the input polygons are not contiguous, this function returns a {@link MultiPolygon} feature. * - * @name union + * @function * @param {Feature} polygon1 input Polygon features * @param {Object} [options={}] Optional Parameters * @param {Object} [options.properties={}] Translate Properties to output Feature diff --git a/packages/turf-unkink-polygon/index.ts b/packages/turf-unkink-polygon/index.ts index 44401c608..5ec560e85 100644 --- a/packages/turf-unkink-polygon/index.ts +++ b/packages/turf-unkink-polygon/index.ts @@ -9,7 +9,7 @@ import { simplepolygon } from "./lib/simplepolygon.js"; * * Uses [simplepolygon](https://github.com/mclaeysb/simplepolygon) internally. * - * @name unkinkPolygon + * @function * @param {FeatureCollection|Feature|Polygon|MultiPolygon} geojson polygons to unkink * @returns {FeatureCollection} Unkinked polygons * @example diff --git a/packages/turf-voronoi/index.ts b/packages/turf-voronoi/index.ts index bdbcd61b5..083e79412 100644 --- a/packages/turf-voronoi/index.ts +++ b/packages/turf-voronoi/index.ts @@ -30,7 +30,7 @@ function coordsToPolygon(coords: Position[]) { * * The Voronoi algorithim used comes from the d3-voronoi package. * - * @name voronoi + * @function * @param {FeatureCollection} points points around which to calculate the Voronoi polygons * @param {Object} [options={}] Optional parameters * @param {BBox} [options.bbox=[-180, -85, 180, -85]] clipping rectangle, in [minX, minY, maxX, MaxY] order