Revise and update docs

geo-types/src/lib.rs

@@ -1,3 +1,11 @@
+#![doc(html_logo_url = "https://raw.githubusercontent.com/georust/meta/master/logo/logo.png")]
+//! The `geo-types` library provides geospatial primitive types and traits to the [`GeoRust`](https://github.com/georust)
+//! crate ecosystem.
+//!
+//! In most cases, you will only need to use this crate if you're a crate author and want compatibility
+//! with other `GeoRust` crates. Otherwise, the [`geo`](https://crates.io/crates/geo) crate re-exports these types and
+//! provides geospatial algorithms, while the [`geojson`](https://crates.io/crates/geojson) crate allows serialising
+//! and de-serialising `geo-types` primitives to GeoJSON.
 extern crate num_traits;
 
 #[cfg(feature = "serde")]

geo-types/src/line_string.rs

@@ -66,12 +66,28 @@ use std::ops::{Index, IndexMut};
 /// }
 /// ```
 ///
+/// You can also iterate over the coordinates in the `LineString` as `Point`s:
+///
+/// ```
+/// use geo_types::{LineString, Coordinate};
+///
+/// let line_string = LineString(vec![
+///     Coordinate { x: 0., y: 0. },
+///     Coordinate { x: 10., y: 0. },
+/// ]);
+///
+/// for point in line_string.points_iter() {
+///     println!("Point x = {}, y = {}", point.x(), point.y());
+/// }
+/// ```
+
 #[derive(PartialEq, Clone, Debug, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct LineString<T>(pub Vec<Coordinate<T>>)
 where
     T: CoordinateType;
 
+/// A `Point` iterator returned by the `points_iter` method
 pub struct PointsIter<'a, T: CoordinateType + 'a>(::std::slice::Iter<'a, Coordinate<T>>);
 
 impl<'a, T: CoordinateType> Iterator for PointsIter<'a, T> {
@@ -89,15 +105,17 @@ impl<'a, T: CoordinateType> DoubleEndedIterator for PointsIter<'a, T> {
 }
 
 impl<T: CoordinateType> LineString<T> {
+    /// Return an iterator yielding the coordinates of a `LineString` as `Point`s
     pub fn points_iter(&self) -> PointsIter<T> {
         PointsIter(self.0.iter())
     }
 
+    /// Return the coordinates of a `LineString` as a `Vec` of `Point`s
     pub fn into_points(self) -> Vec<Point<T>> {
         self.0.into_iter().map(Point).collect()
     }
 
-    /// Return an `Line` iterator that yields one `Line` for each line segment
+    /// Return an iterator yielding one `Line` for each line segment
     /// in the `LineString`.
     ///
     /// # Examples
@@ -126,6 +144,7 @@ impl<T: CoordinateType> LineString<T> {
         })
     }
 
+    /// An iterator which yields the coordinates of a `LineString` as `Triangle`s
     pub fn triangles<'a>(&'a self) -> impl ExactSizeIterator + Iterator<Item = Triangle<T>> + 'a {
         self.0.windows(3).map(|w| {
             // slice::windows(N) is guaranteed to yield a slice with exactly N elements
@@ -166,14 +185,14 @@ impl<T: CoordinateType> LineString<T> {
     }
 }
 
-/// Turn a `Vec` of `Point`-ish objects into a `LineString`.
+/// Turn a `Vec` of `Point`-like objects into a `LineString`.
 impl<T: CoordinateType, IC: Into<Coordinate<T>>> From<Vec<IC>> for LineString<T> {
     fn from(v: Vec<IC>) -> Self {
         LineString(v.into_iter().map(|c| c.into()).collect())
     }
 }
 
-/// Turn a `Point`-ish iterator into a `LineString`.
+/// Turn an iterator of `Point`-like objects into a `LineString`.
 impl<T: CoordinateType, IC: Into<Coordinate<T>>> FromIterator<IC> for LineString<T> {
     fn from_iter<I: IntoIterator<Item = IC>>(iter: I) -> Self {
         LineString(iter.into_iter().map(|c| c.into()).collect())

geo-types/src/point.rs

@@ -6,7 +6,8 @@ use std::ops::Sub;
 
 /// A single point in 2D space.
 ///
-/// Points can be created using the `new(x, y)` constructor, or from a `Coordinate` or pair of points.
+/// Points can be created using the `new(x, y)` constructor, the `point!` macro, a `Coordinate`, or from 
+/// two-element tuples or arrays – see the `From` impl section for a complete list.
 ///
 /// # Examples
 ///
@@ -34,6 +35,12 @@ impl<T: CoordinateType> From<(T, T)> for Point<T> {
     }
 }
 
+impl<T: CoordinateType> From<[T; 2]> for Point<T> {
+    fn from(coords: [T; 2]) -> Point<T> {
+        Point::new(coords[0], coords[1])
+    }
+}
+
 impl<T> Point<T>
 where
     T: CoordinateType,
@@ -379,9 +386,3 @@ where
         }
     }
 }
-
-impl<T: CoordinateType> From<[T; 2]> for Point<T> {
-    fn from(coords: [T; 2]) -> Point<T> {
-        Point::new(coords[0], coords[1])
-    }
-}

geo/src/algorithm/chamberlain_duquette_area.rs

@@ -1,7 +1,7 @@
 use crate::{CoordinateType, LineString, Polygon, EQUATORIAL_EARTH_RADIUS};
 use num_traits::Float;
 
-/// Signed approximate geodesic area of a geometry.
+/// Calculate the signed approximate geodesic area of a `Geometry`.
 ///
 /// # Units
 ///

geo/src/algorithm/closest_point.rs

@@ -3,15 +3,15 @@ use crate::{Closest, Line, LineString, MultiLineString, MultiPoint, MultiPolygon
 use num_traits::Float;
 use std::iter;
 
-/// Find the closest point between two objects, where the other object is
-/// assumed to be a `Point` by default.
+/// Find the closest `Point` between a given geometry and an input `Point`.
+/// The closest point may intersect the geometry, be a single
+/// point, or be indeterminate, as indicated by the value of the returned enum.
 ///
 /// # Examples
 ///
-/// Here's a simple example where we've got a horizontal line which goes
-/// through `(-50, 0) -> (50, 0)` and want to find the closest point to
-/// `(0, 100)`. If you draw it out on paper the point on the line which is
-/// closest to `(0, 100)` will be the origin.
+/// We have a horizontal line which goes through `(-50, 0) -> (50, 0)`,
+/// and want to find the closest point to the point `(0, 100)`.
+/// Drawn on paper, the point on the line which is closest to `(0, 100)` is the origin (0, 0).
 ///
 /// ```rust
 /// # use geo::algorithm::closest_point::ClosestPoint;

geo/src/algorithm/from_postgis.rs

@@ -5,6 +5,7 @@ use crate::{
 use postgis;
 use postgis::ewkb::{GeometryCollectionT, GeometryT};
 
+#[cfg_attr(docsrs, doc(cfg(feature = "postgis")))]
 /// Creates geometry from a PostGIS type.
 ///
 /// Note that PostGIS databases can store data under any spatial