Preliminary improvements to documentation, esp internal types e.g. Un…

…its (#2727) * Added JSDoc for internal types and constants e.g. Unts and earthRadius. Minimal other changes to bring JSDoc types into line with code types. Added GeoJsonProperties to documentation.yml for type linking. * Generated README.md files based on updated source that now includes JSDoc for internal types and constants e.g. Units. Also synced up some out of data JSDoc types with what is in the code. * Switched the structure of documentation.yml to be more traditionally nested. We'll use this new structure from the turf-www repo to generate the website documentation in a more robust manner. * For some reason leaving this function documented as the default (geojsonRbush) causes @turf/turf last-checks to fail. Specifically defining it as rbush like it used to be, except with the @function tag rather than @name.
Turfjs · Oct 11, 2024 · e7227f5 · e7227f5
1 parent 90e91a3
commit e7227f5
Show file tree

Hide file tree

Showing 132 changed files with 1,147 additions and 933 deletions.
diff --git 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
@@ -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
-
 <!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
 
 ---

diff --git 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<LineString>} line input line
+ * @function
+ * @param {Feature<LineString>|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>} 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
@@ -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
@@ -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
@@ -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<LineString|MultiLineString|Polygon|MultiPolygon>} feature feature to clip to the bbox
  * @param {BBox} bbox extent in [minX, minY, maxX, maxY] order
  * @returns {Feature<LineString|MultiLineString|Polygon|MultiPolygon>} clipped Feature