Some edits to docs

Use same tenses, verbs etc. Add doc definitions for `Rect` and `Triangle` Expand and clarify definition of `Polygon`
amandasaurus · Dec 24, 2018 · 904b78c · 904b78c
1 parent d95f564
commit 904b78c
Show file tree

Hide file tree

Showing 12 changed files with 42 additions and 38 deletions.
diff --git a/geo-types/src/geometry_collection.rs b/geo-types/src/geometry_collection.rs
@@ -1,7 +1,7 @@
 use std::iter::FromIterator;
 use {CoordinateType, Geometry};
 
-/// A collection of [`Geometry`](enum.Geometry.html) types
+/// A collection of [`Geometry`](enum.Geometry.html) types.
 ///
 /// Can be created from a `Vec` of Geometries, or from an Iterator which yields Geometries.
 ///

diff --git a/geo-types/src/line.rs b/geo-types/src/line.rs
@@ -1,6 +1,6 @@
 use {Coordinate, CoordinateType, Point};
 
-/// A line segment made up of exactly two [`Point`s](struct.Point.html)
+/// A line segment made up of exactly two [`Point`s](struct.Point.html).
 #[derive(PartialEq, Clone, Copy, Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct Line<T>

diff --git a/geo-types/src/multi_line_string.rs b/geo-types/src/multi_line_string.rs
@@ -1,7 +1,7 @@
 use std::iter::FromIterator;
 use {CoordinateType, LineString};
 
-/// A collection of [`LineString`s](struct.LineString.html)
+/// A collection of [`LineString`s](struct.LineString.html).
 ///
 /// Can be created from a `Vec` of `LineString`s, or from an Iterator which yields `LineString`s.
 ///

diff --git a/geo-types/src/multi_point.rs b/geo-types/src/multi_point.rs
@@ -1,7 +1,7 @@
 use std::iter::FromIterator;
 use {CoordinateType, Point};
 
-/// A collection of [`Point`s](struct.Point.html)
+/// A collection of [`Point`s](struct.Point.html).
 ///
 /// # Examples
 ///

diff --git a/geo-types/src/multi_polygon.rs b/geo-types/src/multi_polygon.rs
@@ -1,7 +1,7 @@
 use std::iter::FromIterator;
 use {CoordinateType, Polygon};
 
-/// A collection of [`Polygon`s](struct.Polygon.html)
+/// A collection of [`Polygon`s](struct.Polygon.html).
 ///
 /// Can be created from a `Vec` of `Polygon`s, or `collect`ed from an Iterator which yields `Polygon`s.
 ///

diff --git a/geo-types/src/point.rs b/geo-types/src/point.rs
@@ -4,7 +4,7 @@ use std::ops::Neg;
 use std::ops::Sub;
 use {Coordinate, CoordinateType};
 
-/// A single Point in 2D space.
+/// A single point in 2D space.
 ///
 /// Points can be created using the `new(x, y)` constructor, or from a `Coordinate` or pair of points.
 ///

diff --git a/geo-types/src/polygon.rs b/geo-types/src/polygon.rs
@@ -1,7 +1,9 @@
 use num_traits::{Float, Signed};
 use {CoordinateType, LineString, Point, Rect};
 
-/// A representation of an area. Its outer boundary is represented by a [`LineString`](struct.LineString.html) that is both closed and simple
+/// A bounded 2D area. Its outer boundary (_shell_) is represented by a [`LineString`](struct.LineString.html)
+/// that is both closed and simple (non-intersecting). It may contain 0 or more non-intersecting holes (_rings_), each represented by
+/// a closed simple `LineString`.
 ///
 /// It has one exterior *ring* or *shell*, and zero or more interior rings, representing holes.
 ///

diff --git a/geo-types/src/rect.rs b/geo-types/src/rect.rs
@@ -1,5 +1,6 @@
 use {Coordinate, CoordinateType};
 
+/// A bounded 2D quadrilateral whose area is defined by minimum and maximum `Coordinates`.
 #[derive(PartialEq, Clone, Copy, Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct Rect<T>

diff --git a/geo-types/src/triangle.rs b/geo-types/src/triangle.rs
@@ -1,5 +1,6 @@
 use {Coordinate, CoordinateType, Line};
 
+/// A bounded 2D area whose three vertices are defined by `Coordinate`s.
 #[derive(Copy, Clone, Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct Triangle<T: CoordinateType>(pub Coordinate<T>, pub Coordinate<T>, pub Coordinate<T>);

diff --git a/geo/src/algorithm/extremes.rs b/geo/src/algorithm/extremes.rs
@@ -85,7 +85,7 @@ where
 }
 
 pub trait ExtremeIndices<T: Float + Signed> {
-    /// Find the extreme `x` and `y` indices of a convex Polygon
+    /// Find the extreme `x` and `y` _indices_ of a convex Polygon
     ///
     /// The polygon **must be convex and properly (ccw) oriented**.
     ///
@@ -136,7 +136,7 @@ where
 }
 
 pub trait ExtremePoints<T: Float> {
-    /// Find the extreme `x` and `y` points of a Geometry
+    /// Find the extreme `x` and `y` `Point`s of a Geometry
     ///
     /// This trait is available to any struct implementing both `ConvexHull` amd `ExtremeIndices`
     ///

diff --git a/geo/src/algorithm/mod.rs b/geo/src/algorithm/mod.rs
@@ -1,59 +1,59 @@
-/// Returns the area of the surface of a geometry.
+/// Calculate the area of the surface of a `Geometry`.
 pub mod area;
-/// Returns the bearing to another Point in degrees.
+/// Calculate the bearing to another `Point`, in degrees.
 pub mod bearing;
-/// Returns the bounding rectangle of a geometry.
+/// Calculate the bounding rectangle of a `Geometry`.
 pub mod bounding_rect;
-/// Calculation of the centroid of a geometry.
+/// Calculate the centroid of a `Geometry`.
 pub mod centroid;
-/// Determine the minimum distance between two objects.
+/// Calculate the minimum distance between two `Geometries`.
 pub mod closest_point;
-/// Checks if the geometry A is completely inside the B geometry.
+/// Determine whether `Geometry` `A` is completely enclosed by `Geometry` `B`.
 pub mod contains;
-/// Calculates the convex hull of a geometry.
+/// Calculate the convex hull of a `Geometry`.
 pub mod convexhull;
-/// Returns the Euclidean distance between two geometries.
+/// Calculate the Euclidean distance between two `Geometries`.
 pub mod euclidean_distance;
-/// Returns the length of a line.
+/// Calculate the length of a planar line between two `Geometries`.
 pub mod euclidean_length;
-/// Returns the extreme indices of a `Polygon`, `MultiPolygon`, or `MultiPoint`.
+/// Calculate the extreme indices of a `Polygon`, `MultiPolygon`, or `MultiPoint`.
 pub mod extremes;
-/// Produces geometry from PostGIS.
+/// Produces a `Geometry` from PostGIS.
 #[cfg(feature = "postgis-integration")]
 pub mod from_postgis;
-/// Returns a new Point using distance and bearing.
+/// Calculate a new Point given a distance and a bearing.
 pub mod haversine_destination;
-/// Returns the Haversine distance between two geometries.
+/// Calculate the Haversine distance between two `Geometries`.
 pub mod haversine_distance;
-/// Returns a new Point along a great circle between two points.
+/// Calculate a new `Point` lying on a Great Circle arc between two `Point`s.
 pub mod haversine_intermediate;
-/// Returns the Haversine length of a line.
+/// Calculate the Haversine length of a Line.
 pub mod haversine_length;
-/// Checks if the geometry A intersects the geometry B.
+/// Determine whether `Geometry` `A` intersects `Geometry` `B`.
 pub mod intersects;
-/// Apply a function to all coordinates.
+/// Apply a function to all `Coordinates` of a `Geometry`.
 pub mod map_coords;
-/// Orients a Polygon's exterior and interior rings.
+/// Orient a `Polygon`'s exterior and interior rings.
 pub mod orient;
-/// Helper functions for the "fast path" variant of the Polygon-Polygon distance method.
+/// Helper functions for the "fast path" variant of the Polygon-Polygon Euclidean distance method.
 pub(crate) mod polygon_distance_fast_path;
 /// Coordinate projections and transformations using [PROJ](http://proj4.org) v5.0.x.
 #[cfg(feature = "use-proj")]
 pub mod proj;
-/// Rotate a geometry around either its centroid or a point by an angle given in degrees.
+/// Rotate a `Geometry` around either its centroid or a `Point` by an angle given in degrees.
 pub mod rotate;
-/// Simplifies geometries using the Ramer-Douglas-Peucker algorithm.
+/// Simplify `Geometries` using the Ramer-Douglas-Peucker algorithm.
 pub mod simplify;
-/// Simplifies geometries using the Visvalingam-Whyatt algorithm. Includes a topology-preserving variant.
+/// Simplify `Geometries` using the Visvalingam-Whyatt algorithm. Includes a topology-preserving variant.
 pub mod simplifyvw;
-/// Converts geometries into PostGIS types.
+/// Convert `Geometries` into PostGIS types.
 #[cfg(feature = "postgis-integration")]
 pub mod to_postgis;
-/// Translates a geometry along the given offsets.
+/// Translate a `Geometry` along the given offsets.
 pub mod translate;
-/// Calculate the Vincenty distance between Points.
+/// Calculate the Vincenty distance between two `Point`s.
 pub mod vincenty_distance;
-/// Calculate the Vincenty length of a LineString.
+/// Calculate the Vincenty length of a `LineString`.
 pub mod vincenty_length;
-/// Calculate and work with the winding order of Linestrings.
+/// Calculate and work with the winding order of `Linestring`s.
 pub mod winding_order;
diff --git a/geo/src/types.rs b/geo/src/types.rs
@@ -3,7 +3,7 @@ use {CoordinateType, Point};
 
 pub use geo_types::private_utils::COORD_PRECISION;
 
-/// A container for indices of the minimum and maximum points of a [`Geometry`](enum.Geometry.html)
+/// A container for _indices_ of the minimum and maximum `Point`s of a [`Geometry`](enum.Geometry.html).
 #[cfg_attr(feature = "use-serde", derive(Serialize, Deserialize))]
 #[derive(PartialEq, Clone, Copy, Debug)]
 pub struct Extremes {
@@ -24,7 +24,7 @@ impl From<Vec<usize>> for Extremes {
     }
 }
 
-/// A container for the coordinates of the minimum and maximum points of a [`Geometry`](enum.Geometry.html)
+/// A container for the _coordinates_ of the minimum and maximum `Point`s of a [`Geometry`](enum.Geometry.html).
 #[cfg_attr(feature = "use-serde", derive(Serialize, Deserialize))]
 #[derive(PartialEq, Clone, Copy, Debug)]
 pub struct ExtremePoint<T>