Clarify behavior of some existing turf modules

packages/turf-area/index.ts

@@ -3,10 +3,10 @@ import { earthRadius } from "@turf/helpers";
 import { geomReduce } from "@turf/meta";
 
 /**
- * Takes one or more features and returns their area in square meters.
+ * Calculates the geodesic area in square meters of one or more polygons.
  *
  * @name area
- * @param {GeoJSON} geojson input GeoJSON feature(s)
+ * @param {GeoJSON} geojson input polygon(s) as {@link Geometry}, {@link Feature}, or {@link FeatureCollection}
  * @returns {number} area in square meters
  * @example
  * var polygon = turf.polygon([[[125, -15], [113, -22], [154, -27], [144, -15], [125, -15]]]);

packages/turf-helpers/README_UNITS.md

@@ -0,0 +1,37 @@
+# @turf/helpers
+
+## Units
+
+* meters
+* metres
+* millimeters
+* millimetres
+* centimeters
+* centimetres
+* kilometers
+* kilometres
+* miles
+* nauticalmiles
+* inches
+* yards
+* feet
+* radians
+* degrees
+
+## AreaUnits
+
+* meters
+* metres
+* millimeters
+* millimetres
+* centimeters
+* centimetres
+* kilometers
+* kilometres
+* miles
+* nauticalmiles
+* inches
+* yards
+* feet
+* acres
+* hectares

packages/turf-helpers/index.ts

@@ -57,15 +57,14 @@ export type AllGeoJSON =
  */
 
 /**
- * Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
- *
+ * 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}
  */
 export const earthRadius = 6371008.8;
 
 /**
- * Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
+ * 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
  *

packages/turf-point-grid/index.ts

@@ -12,13 +12,13 @@ import { distance } from "@turf/distance";
 import { point, featureCollection, Units } from "@turf/helpers";
 
 /**
- * Creates a {@link Point} grid from a bounding box, {@link FeatureCollection} or {@link Feature}.
+ * Creates a grid of points
  *
  * @name pointGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide the distance between points, in units
+ * @param {BBox} bbox extent of grid in [minX, minY, maxX, maxY] order
+ * @param {number} cellSide the distance between points
  * @param {Object} [options={}] Optional parameters
- * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees, radians, miles, or kilometers
+ * @param {Units} [options.units='kilometers'] the units of the cellSide value.  Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid
  * @returns {FeatureCollection<Point>} grid of points

packages/turf-rectangle-grid/index.ts

@@ -14,15 +14,17 @@ import {
   Units,
 } from "@turf/helpers";
 /**
- * Creates a grid of rectangles from a bounding box, {@link Feature} or {@link FeatureCollection}.
+ * Creates a grid of rectangular polygons with width and height consistent in degrees
  *
  * @name rectangleGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellWidth of each cell, in units
- * @param {number} cellHeight of each cell, in units
+ * @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
  * @param {Object} [options={}] Optional parameters
- * @param {string} [options.units='kilometers'] units ("degrees", "radians", "miles", "kilometers") that the given cellWidth
- * and cellHeight are expressed in. Converted at the southern border.
+ * @param {Units} [options.units='kilometers'] the units of the cell width and height value.
+ * Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}.
+ * If you are looking for rectangles with equal width and height in linear units (e.g. kilometers) this is not the module for you.
+ * The cellWidth and cellHeight is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees.
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon,
  * the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid

packages/turf-square-grid/index.ts

@@ -10,18 +10,20 @@ import { Units } from "@turf/helpers";
 import { rectangleGrid } from "@turf/rectangle-grid";
 
 /**
- * Creates a square grid from a bounding box.
+ * Creates a grid of square polygons with cell length consistent in degrees
  *
  * @name squareGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide of each cell, in units
+ * @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
- * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees,
- * radians, miles, or kilometers
+ * @param {Units} [options.units='kilometers'] the units of the cellSide value.
+ * Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}.
+ * If you are looking for squares with sides of equal lengths in linear units (e.g. kilometers) this is not the module for you.
+ * The cellSide is converted from units provided to degrees internally, so the width and height of resulting polygons will be consistent only in degrees.
  * @param {Feature<Polygon|MultiPolygon>} [options.mask] if passed a Polygon or MultiPolygon,
  * the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid
- * @returns {FeatureCollection<Polygon>} grid a grid of polygons
+ * @returns {FeatureCollection<Polygon>} a grid of polygons with equal width and height in degrees.
  * @example
  * var bbox = [-95, 30 ,-85, 40];
  * var cellSide = 50;

packages/turf-triangle-grid/index.ts

@@ -10,13 +10,13 @@ import { intersect } from "@turf/intersect";
 import { polygon, featureCollection, Units } from "@turf/helpers";
 
 /**
- * Takes a bounding box and a cell depth and returns a set of triangular {@link Polygon|polygons} in a grid.
+ * Creates a grid of triangular polygons.
  *
  * @name triangleGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide dimension of each cell
+ * @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
- * @param {string} [options.units='kilometers'] used in calculating cellSide, can be degrees, radians, miles, or kilometers
+ * @param {Units} [options.units='kilometers'] used in calculating cellSide.  Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/README_UNITS.md Units}
  * @param {Feature<Polygon>} [options.mask] if passed a Polygon or MultiPolygon, the grid Points will be created only inside it
  * @param {Object} [options.properties={}] passed to each point of the grid
  * @returns {FeatureCollection<Polygon>} grid of polygons