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/index.ts

@@ -57,15 +57,17 @@ export type AllGeoJSON =
  */
 
 /**
- * Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
- *
+ * The {@link https://en.wikipedia.org/wiki/Earth_radius#Arithmetic_mean_radius arithmetic mean radius} of the Earth.
+ * Used by Turf modules that model the Earth as a sphere. This radii value
+ * was chosen over others because it is {@link https://rosettacode.org/wiki/Haversine_formula#:~:text=This%20value%20is%20recommended recommended for use} with the Haversine formula,
+ * used by turf/distance.
  * @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 equatorial 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 {Array<number>} 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 {string} [options.units='kilometers'] the units of the cellSide value.  Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts 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,14 @@ import {
   Units,
 } from "@turf/helpers";
 /**
- * Creates a grid of rectangles from a bounding box, {@link Feature} or {@link FeatureCollection}.
+ * Creates a grid of rectangular polygon cells of equal width and height 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 {Array<number>} 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 {string} [options.units='kilometers'] the units of the cellWidth and cellLenth values. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellWidth and cellLength values are converted to degrees, regardless of units specified.
  * @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,18 @@ import { Units } from "@turf/helpers";
 import { rectangleGrid } from "@turf/rectangle-grid";
 
 /**
- * Creates a square grid from a bounding box.
+ * Creates a grid of square polygon cells with equal length sides in degrees.
  *
  * @name squareGrid
- * @param {Array<number>} bbox extent in [minX, minY, maxX, maxY] order
- * @param {number} cellSide of each cell, in units
+ * @param {Array<number>} 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,
+ * @param {string} [options.units='kilometers'] the units of the cellSide value. Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts Units}. Internally cellSide value is converted to degrees, regardless of units specified.
  * radians, miles, or kilometers
  * @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 {Array<number>} 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 {string} [options.units='kilometers'] used in calculating cellSide.  Supports all valid Turf {@link https://github.com/Turfjs/turf/blob/master/packages/turf-helpers/index.ts 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