documentation work

lib/src/bearing.dart

@@ -3,6 +3,9 @@ import 'dart:math';
 import 'geojson.dart';
 import 'helpers.dart';
 
+// http://en.wikipedia.org/wiki/Haversine_formula
+// http://www.movable-type.co.uk/scripts/latlong.html
+
 num bearingRaw(Position start, Position end, {bool calcFinal = false}) {
   // Reverse calculation
   if (calcFinal == true) {
@@ -19,6 +22,22 @@ num bearingRaw(Position start, Position end, {bool calcFinal = false}) {
   return radiansToDegrees(atan2(a, b));
 }
 
+/// Takes two [Point]s and finds the geographic bearing between them,
+/// i.e. the angle measured in degrees from the north line (0 degrees)
+/// For example:
+///
+/// ```dart
+/// var point1 = Point(coordinates: Position(-75.343, 39.984));
+/// var point2 = Point(coordinates: Position((-75.543, 39.123));
+///
+/// var bearing = bearing(point1, point2);
+/// //addToMap
+/// var addToMap = [point1, point2]
+/// point1.properties['marker-color'] = '#f00'
+/// point2.properties['marker-color'] = '#0f0'
+/// point1.properties.bearing = bearing
+/// ```
+
 num bearing(Point start, Point end, {bool calcFinal = false}) =>
     bearingRaw(start.coordinates, end.coordinates, calcFinal: calcFinal);
 
@@ -28,5 +47,6 @@ num calculateFinalBearingRaw(Position start, Position end) {
   return reverseBearing.remainder(360);
 }
 
+/// Calculates Final Bearing
 num calculateFinalBearing(Point start, Point end) =>
     calculateFinalBearingRaw(start.coordinates, end.coordinates);

lib/src/destination.dart

@@ -22,6 +22,25 @@ Position destinationRaw(Position origin, num distance, num bearing,
   );
 }
 
+/// Takes a [Point] and calculates the location of a destination point given a distance in
+/// 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.
+/// For example:
+///
+/// ```dart
+/// var point = Point(coordinates: Position(-75.343, 39.984));
+/// var distance = 50;
+/// var bearing = 90;
+/// var options = Unit.miles;
+///
+/// var destination = destination(point, distance, bearing, options);
+///
+/// //addToMap
+/// var addToMap = [point, destination]
+/// destination.properties['marker-color'] = '#f00';
+/// point.properties['marker-color'] = '#0f0';
+/// ```
+
 Point destination(Point origin, num distance, num bearing,
         [Unit unit = Unit.kilometers]) =>
     Point(

lib/src/distance.dart

@@ -3,6 +3,9 @@ import 'dart:math';
 import 'geojson.dart';
 import 'helpers.dart';
 
+//http://en.wikipedia.org/wiki/Haversine_formula
+//http://www.movable-type.co.uk/scripts/latlong.html
+
 num distanceRaw(Position from, Position to, [Unit unit = Unit.kilometers]) {
   var dLat = degreesToRadians((to.lat - from.lat));
   var dLon = degreesToRadians((to.lng - from.lng));
@@ -14,5 +17,16 @@ num distanceRaw(Position from, Position to, [Unit unit = Unit.kilometers]) {
   return radiansToLength(2 * atan2(sqrt(a), sqrt(1 - a)), unit);
 }
 
+/// Calculates the distance between two [Point]s in degrees, radians, miles, or kilometers.
+///  This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.
+///  For example:
+///
+/// ```dart
+/// var from = Point(coordinates: Position(-75.343, 39.984));
+/// var to = Point(coordinates: Position(-75.443, 39.984));
+/// var options = Unit.miles;
+///
+/// var distance = distance(from, to, options);
+/// ```
 num distance(Point from, Point to, [Unit unit = Unit.kilometers]) =>
     distanceRaw(from.coordinates, to.coordinates, unit);

lib/src/helpers.dart

@@ -30,8 +30,11 @@ enum Corner {
   centroid,
 }
 
+/// Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
 const earthRadius = 6371008.8;
 
+/// Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
+/// Keys are the name of the unit, values are the number of that unit in a single radian
 const factors = <Unit, num>{
   Unit.centimeters: earthRadius * 100,
   Unit.degrees: earthRadius / 111325,
@@ -60,6 +63,7 @@ const unitsFactors = <Unit, num>{
   Unit.yards: 1 / 1.0936,
 };
 
+/// Area of measurement factors based on 1 square meter.
 const areaFactors = <Unit, num>{
   Unit.acres: 0.000247105,
   Unit.centimeters: 10000,
@@ -72,6 +76,7 @@ const areaFactors = <Unit, num>{
   Unit.yards: 1.195990046,
 };
 
+/// Round number to precision
 num round(num value, [num precision = 0]) {
   if (!(precision >= 0)) {
     throw Exception("precision must be a positive number");
@@ -81,6 +86,8 @@ num round(num value, [num precision = 0]) {
   return result.round() / multiplier;
 }
 
+/// 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
 num radiansToLength(num radians, [Unit unit = Unit.kilometers]) {
   var factor = factors[unit];
   if (factor == null) {
@@ -89,6 +96,8 @@ num radiansToLength(num radians, [Unit unit = Unit.kilometers]) {
   return radians * factor;
 }
 
+/// 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
 num lengthToRadians(num distance, [Unit unit = Unit.kilometers]) {
   num? factor = factors[unit];
   if (factor == null) {
@@ -97,10 +106,14 @@ num lengthToRadians(num distance, [Unit unit = Unit.kilometers]) {
   return distance / factor;
 }
 
+/// 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
 num lengthToDegrees(num distance, [Unit unit = Unit.kilometers]) {
   return radiansToDegrees(lengthToRadians(distance, unit));
 }
 
+/// 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
 num bearingToAzimuth(num bearing) {
   num angle = bearing.remainder(360);
   if (angle < 0) {
@@ -109,16 +122,20 @@ num bearingToAzimuth(num bearing) {
   return angle;
 }
 
+/// Converts an angle in radians to degrees
 num radiansToDegrees(num radians) {
   num degrees = radians.remainder(2 * pi);
   return degrees * 180 / pi;
 }
 
+/// Converts an angle in degrees to radians
 num degreesToRadians(num degrees) {
   num radians = degrees.remainder(360);
   return radians * pi / 180;
 }
 
+/// Converts a length to the requested unit.
+/// Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 num convertLength(
   num length, [
   Unit originalUnit = Unit.kilometers,
@@ -130,6 +147,8 @@ num convertLength(
   return radiansToLength(lengthToRadians(length, originalUnit), finalUnit);
 }
 
+/// Converts a area to the requested unit.
+/// Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares
 num convertArea(num area,
     [originalUnit = Unit.meters, finalUnit = Unit.kilometers]) {
   if (area < 0) {

lib/src/invariant.dart

@@ -26,11 +26,12 @@ Position getCoord(dynamic coord) {
   throw Exception("coord must be GeoJSON Point or Position");
 }
 
-/// Unwrap coordinates from a [Feature], [GeometryObject] or a [List]
+/// Unwraps coordinates from a [Feature], [GeometryObject] or a [List]
 ///
 /// Gets a [List<dynamic>], [GeometryObject] or a [Feature] or a [List<dynamic>] and
 /// returns [List<dynamic>].
 /// For example:
+///
 /// ```dart
 /// var polygon = Polygon(coordinates: [
 ///    [

lib/src/line_segment.dart

@@ -3,8 +3,6 @@ import 'package:turf/src/meta/flatten.dart';
 
 import 'geojson.dart';
 
-// export default lineSegment;
-
 /// Creates a [FeatureCollection] of 2-vertex [LineString] segments from a
 /// [LineString] or [MultiLineString] or [Polygon] and [MultiPolygon]
 /// Returns [FeatureCollection<LineString>] 2-vertex line segments
@@ -210,7 +208,7 @@ typedef T? SegmentReduceCallback<T>(
   int segmentIndex,
 );
 
-/// Reduce 2-vertex line segment in any GeoJSON object, similar to [Iterable.reduce]()
+/// Reduces 2-vertex line segment in any GeoJSON object, similar to [Iterable.reduce]()
 /// (Multi)Point geometries do not contain segments therefore they are ignored during this operation.
 ///
 /// Takes [FeatureCollection], [Feature], [GeoJSONObject], a

lib/src/meta/feature.dart

@@ -8,7 +8,6 @@ typedef FeatureEachCallback = dynamic Function(
 
 /// Iterates over features in any [geoJSONObject], calling [callback] on each
 /// iteration. Similar to [Iterable.forEach].
-///
 /// For example:
 ///
 /// ```dart

lib/src/midpoint.dart

@@ -11,6 +11,20 @@ Position midpointRaw(Position point1, Position point2) {
   return midpoint;
 }
 
+/// Takes two [Point]s and returns a point midway between them.
+/// The midpoint is calculated geodesically, meaning the curvature of the earth is taken into account.
+/// For example:
+///
+/// ```
+/// var point1 = Point(coordinates: Position(-75.343, 39.984));
+/// var point2 = Point(coordinates: Position((-75.543, 39.123));
+///
+/// var midpoint = midpoint(point1, point2);
+///
+/// //addToMap
+/// var addToMap = [point1, point2, midpoint];
+/// midpoint.properties['marker-color'] = '#f00';
+/// ```
 Point midpoint(Point point1, Point point2) => Point(
       coordinates: midpointRaw(point1.coordinates, point2.coordinates),
     );

lib/src/nearest_point.dart

@@ -1,6 +1,29 @@
 import 'distance.dart';
 import 'geojson.dart';
 
+/// Takes a reference [Point] and a FeatureCollection of Features
+/// with Point geometries and returns the
+/// point from the FeatureCollection closest to the reference. This calculation
+/// is geodesic. For example:
+///
+/// ```dart
+/// var targetPoint = Point(coordinates: Position(-75.943, 39.984));
+/// Feature feature =
+///    Feature(geometry: targetPoint, properties: {"marker-color": "#0F0"});
+/// FeatureCollection points = FeatureCollection(features: [
+///   Feature(geometry: Point(coordinates: Position(-75.343, 39.984))),
+///   Feature(geometry: Point(coordinates: Position(-75.443, 39.984))),
+///   Feature(geometry: Point(coordinates: Position(-75.543, 39.984))),
+///   Feature(geometry: Point(coordinates: Position(-75.643, 39.984))),
+/// ]);
+///
+/// var nearest = nearestPoint(targetPoint, points);
+///
+/// //addToMap
+/// var addToMap = [targetPoint, points, nearest];
+/// nearest.properties['marker-color'] = '#F00';
+/// ```
+
 Feature<Point> nearestPoint(
     Feature<Point> targetPoint, FeatureCollection<Point> points) {
   Feature<Point> nearest;

lib/turf.dart

@@ -1,6 +1,3 @@
-/// Support for doing something awesome.
-///
-/// More dartdocs go here.
 library turf;
 
 export 'src/bearing.dart';

test/components/meta_test.dart

@@ -665,7 +665,6 @@ main() {
 
     // Each Iterators
     // meta.segmentEach has been purposely excluded from this list
-    // TODO fill out this list with all 'each' iterators
     test('geomEach', () {
       runBreakingIterationTest(geomEach, (geom, i, props, bbox, id) {
         iterationCount += 1;