Merge pull request #1305 from georust/mkirk/line-measure-docs-2

docs: add example to line_measure

Author: michaelkirk

geo/src/algorithm/line_measures/bearing.rs

@@ -9,5 +9,18 @@ pub trait Bearing<F: CoordFloat> {
     /// # Units
     /// - `origin`, `destination`: Point where the units of x/y depend on the [trait implementation](#implementors).
     /// - returns: degrees, where: North: 0°, East: 90°, South: 180°, West: 270°
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use geo::{Point, Haversine, Bearing, Geodesic};
+    ///
+    /// let point_1 = Point::new(0.0, 0.0);
+    /// let point_2 = Point::new(0.0, 2.0);
+    ///
+    /// // Due north
+    /// assert_eq!(Haversine::bearing(point_1, point_2), 0.0);
+    /// assert_eq!(Geodesic::bearing(point_1, point_2), 0.0);
+    /// ```
     fn bearing(origin: Point<F>, destination: Point<F>) -> F;
 }

geo/src/algorithm/line_measures/densify.rs

@@ -12,6 +12,7 @@ use num_traits::FromPrimitive;
 /// - `max_segment_length` units depend on the implementing [metric space]. It must be greater than 0.
 ///
 /// # Examples
+///
 /// ```
 /// # use approx::assert_relative_eq;
 /// use geo::{wkt, Densify};

geo/src/algorithm/line_measures/destination.rs

@@ -14,6 +14,19 @@ pub trait Destination<F: CoordFloat> {
     /// - `distance`: depends on the [trait implementation](#implementors).
     /// - returns: Point where the units of x/y depend on the [trait implementation](#implementors).
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use approx::assert_relative_eq;
+    /// use geo::{Haversine, Rhumb, Geodesic, Destination, Point};
+    ///
+    /// let point = Point::new(0.0, 0.0);
+    ///
+    /// assert_relative_eq!(Haversine::destination(point, 45.0, 111_111.0), Point::new(0.706607921147679, 0.7065541919063233));
+    /// assert_relative_eq!(Geodesic::destination(point, 45.0, 111_111.0), Point::new(0.7058183774535367, 0.7105205988658333));
+    /// assert_relative_eq!(Rhumb::destination(point, 45.0, 111_111.0), Point::new(0.706590011673029, 0.7065721019258285));
+    /// ```
+    ///
     /// [`metric_spaces`]: super::metric_spaces
     fn destination(origin: Point<F>, bearing: F, distance: F) -> Point<F>;
 }

geo/src/algorithm/line_measures/distance.rs

@@ -8,5 +8,20 @@ pub trait Distance<F, Origin, Destination> {
     ///
     /// - `origin`, `destination`: geometry where the units of x/y depend on the trait implementation.
     /// - returns: depends on the trait implementation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use geo::{Haversine, Euclidean, Distance, Point};
+    /// let p1: Point = Point::new(0.0, 0.0);
+    /// let p2: Point = Point::new(0.0, 2.0);
+    ///
+    /// assert_eq!(Euclidean::distance(p1, p2), 2.0);
+    ///
+    /// // The units of the output depend on the metric space.
+    /// // In the case of [`Haversine`], it's meters.
+    /// // See the documentation for each metric space for details.
+    /// assert_eq!(Haversine::distance(p1, p2).round(), 222_390.0);
+    /// ```
     fn distance(origin: Origin, destination: Destination) -> F;
 }

geo/src/algorithm/line_measures/interpolate_point.rs

@@ -5,6 +5,23 @@ pub trait InterpolatePoint<F: CoordFloat> {
     /// Returns a new Point along a line between two existing points.
     ///
     /// See [specific implementations](#implementors) for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use approx::assert_relative_eq;
+    /// use geo::{Haversine, Euclidean, InterpolatePoint, Point};
+    ///
+    /// let p1: Point = Point::new(0.0, 0.0);
+    /// let p2: Point = Point::new(0.0, 2.0);
+    ///
+    /// assert_relative_eq!(Euclidean::point_at_distance_between(p1, p2, 0.5), Point::new(0.0, 0.5));
+    ///
+    /// // The units of the argument depend on the metric space.
+    /// // In the case of [`Haversine`], it's meters.
+    /// // See the documentation for each metric space for details.
+    /// assert_relative_eq!(Haversine::point_at_distance_between(p1, p2, 111_111.0), Point::new(0.0, 0.9992438493379715));
+    /// ```
     fn point_at_distance_between(
         start: Point<F>,
         end: Point<F>,
@@ -14,6 +31,18 @@ pub trait InterpolatePoint<F: CoordFloat> {
     /// Returns a new Point along a line between two existing points.
     ///
     /// See [specific implementations](#implementors) for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use approx::assert_relative_eq;
+    /// use geo::{Haversine, Euclidean, InterpolatePoint, Point};
+    /// let p1: Point = Point::new(0.0, 0.0);
+    /// let p2: Point = Point::new(20.0, 20.0);
+    ///
+    /// assert_relative_eq!(Euclidean::point_at_ratio_between(p1, p2, 0.5), Point::new(10.0, 10.0));
+    /// assert_relative_eq!(Haversine::point_at_ratio_between(p1, p2, 0.5), Point::new(9.685895184381804, 10.150932342575631));
+    /// ```
     fn point_at_ratio_between(start: Point<F>, end: Point<F>, ratio_from_start: F) -> Point<F>;
 
     /// Interpolates `Point`s along a line between `start` and `end`.
@@ -25,6 +54,26 @@ pub trait InterpolatePoint<F: CoordFloat> {
     /// `max_distance`, no additional points will be included in the output.
     ///
     /// `include_ends`: Should the start and end points be included in the output?
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use approx::assert_relative_eq;
+    /// use geo::{Haversine, Euclidean, InterpolatePoint, Point, MultiPoint, LineString, wkt};
+    /// let p1: Point = Point::new(0.0, 0.0);
+    /// let p2: Point = Point::new(0.0, 2.0);
+    ///
+    /// let intermediate_points: Vec<Point> = Euclidean::points_along_line(p1, p2, 0.5, false).collect();
+    /// let multi_point = MultiPoint(intermediate_points);
+    /// assert_relative_eq!(multi_point, wkt!(MULTIPOINT(0. 0.5,0. 1.,0. 1.5)));
+    ///
+    /// // The units of the argument depend on the metric space.
+    /// // In the case of [`Haversine`], it's meters.
+    /// // See the documentation for each metric space for details.
+    /// let intermediate_points: Vec<Point> = Haversine::points_along_line(p1, p2, 55_555.0, false).collect();
+    /// let multi_point = MultiPoint(intermediate_points);
+    /// assert_relative_eq!(multi_point, wkt!(MULTIPOINT(0. 0.4,0. 0.8,0. 1.2,0. 1.6)));
+    /// ```
     fn points_along_line(
         start: Point<F>,
         end: Point<F>,

geo/src/algorithm/line_measures/mod.rs

@@ -1,4 +1,23 @@
 //! Line measurements like [`Bearing`] and [`Distance`] for various metric spaces like [`Euclidean`], [`Haversine`], [`Geodesic`], and [`Rhumb`].
+//!
+//! ## Example
+//! ```
+//! use geo::{Haversine, Euclidean, Distance, Point, Bearing};
+//! let p1: Point = Point::new(0.0, 0.0);
+//! let p2: Point = Point::new(0.0, 2.0);
+//!
+//! assert_eq!(Euclidean::distance(p1, p2), 2.0);
+//!
+//! // The units of the output depend on the metric space.
+//! // In the case of [`Haversine`], it's meters.
+//! // See the documentation for each metric space for details.
+//! assert_eq!(Haversine::distance(p1, p2).round(), 222_390.0);
+//!
+//! // Due north
+//! assert_eq!(Haversine::bearing(p1, p2), 0.0);
+//! ```
+//!
+//! See the individual [`metric_spaces`] or algorithm [traits](#traits) for more details.
 
 mod bearing;
 pub use bearing::Bearing;