Mark old nearest-point-on-line properties as deprecated (#3005)

* Deprecate old properties in nearestPointOnLine
Modify generate-readmes script to exclude deprecated tags

* Use new nearestPointOnLine properties everywhere
Affects lineOverlap, lineSlice, lineSplit and pointToLineDistance

---------

Co-authored-by: mfedderly <24275386+mfedderly@users.noreply.github.com>

Author: EmilJunker

packages/turf-line-overlap/index.ts

@@ -88,10 +88,10 @@ function lineOverlap<
           tolerance === 0
             ? booleanPointOnLine(coordsSegment[0], match) &&
               booleanPointOnLine(coordsSegment[1], match)
-            : nearestPointOnLine(match, coordsSegment[0]).properties.dist! <=
-                tolerance &&
-              nearestPointOnLine(match, coordsSegment[1]).properties.dist! <=
-                tolerance
+            : nearestPointOnLine(match, coordsSegment[0]).properties
+                .pointDistance! <= tolerance &&
+              nearestPointOnLine(match, coordsSegment[1]).properties
+                .pointDistance! <= tolerance
         ) {
           doesOverlaps = true;
           if (overlapSegment) {
@@ -102,10 +102,10 @@ function lineOverlap<
           tolerance === 0
             ? booleanPointOnLine(coordsMatch[0], segment) &&
               booleanPointOnLine(coordsMatch[1], segment)
-            : nearestPointOnLine(segment, coordsMatch[0]).properties.dist! <=
-                tolerance &&
-              nearestPointOnLine(segment, coordsMatch[1]).properties.dist! <=
-                tolerance
+            : nearestPointOnLine(segment, coordsMatch[0]).properties
+                .pointDistance! <= tolerance &&
+              nearestPointOnLine(segment, coordsMatch[1]).properties
+                .pointDistance! <= tolerance
         ) {
           // Do not define (doesOverlap = true) since more matches can occur within the same segment
           // doesOverlaps = true;

packages/turf-line-split/index.ts

@@ -239,7 +239,7 @@ function findClosestFeature(
   var closestDistance = Infinity;
   featureEach(lines, function (segment) {
     var pt = nearestPointOnLine(segment, point);
-    var dist = pt.properties.dist;
+    var dist = pt.properties.pointDistance;
     if (dist < closestDistance) {
       closestFeature = segment;
       closestDistance = dist;

packages/turf-nearest-point-on-line/index.ts

@@ -65,10 +65,16 @@ function nearestPointOnLine<G extends LineString | MultiLineString>(
     lineDistance: number;
     segmentDistance: number;
     pointDistance: number;
+    // deprecated properties START
+    /** @deprecated use `lineStringIndex` instead */
     multiFeatureIndex: number;
+    /** @deprecated use `segmentIndex` instead */
     index: number;
+    /** @deprecated use `totalDistance` instead */
     location: number;
+    /** @deprecated use `pointDistance` instead */
     dist: number;
+    // deprecated properties END
     [key: string]: any;
   }
 > {

packages/turf-point-to-line-distance/index.ts

@@ -108,7 +108,7 @@ function distanceToSegment(
     const nearest = nearestPointOnLine(lineString([a, b]).geometry, p, {
       units: "degrees",
     });
-    return nearest.properties.dist;
+    return nearest.properties.pointDistance;
   }
 
   // Perform scalar calculations instead using rhumb lines.

scripts/generate-readmes.ts

@@ -51,6 +51,12 @@ const yaml = require("yamljs");
         if (res === undefined) return console.warn(packagePath);
         console.log("Building Docs: " + name);
 
+        // Workaround to exclude @deprecated tags from docs
+        // See https://github.com/documentationjs/documentation/issues/1596
+        res = res.filter((item) =>
+          item.tags.every((tag) => tag.title !== "deprecated")
+        );
+
         // Format Markdown
         documentation.formats
           .md(res, { paths })