Merge #591

591: Improve geo-types documentation. r=michaelkirk a=frewsxcv - [x] I agree to follow the project's [code of conduct](https://github.com/georust/geo/blob/master/CODE_OF_CONDUCT.md). - [ ] ~I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.~ --- ![Screen Shot 2021-01-01 at 12 59 51 PM](https://user-images.githubusercontent.com/416575/103444025-c0b38b80-4c32-11eb-8ca7-0af13843eee1.png) Co-authored-by: Corey Farwell <coreyf@rwell.org>
georust · Jan 1, 2021 · 7dc6ef4 · 7dc6ef4
2 parents 5a85dde + 8c3680f
commit 7dc6ef4
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 17 deletions.
diff --git a/geo-types/src/lib.rs b/geo-types/src/lib.rs
@@ -1,23 +1,39 @@
 #![warn(missing_debug_implementations)]
 #![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.
+//! The `geo-types` library provides geospatial primitive types for the [GeoRust] 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.
+//! 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.
+//!
+//! # Types
+//!
+//! - **[`Coordinate`]**: A two-dimensional coordinate. All geometry types are composed of [`Coordinate`]s, though [`Coordinate`] itself is not a [`Geometry`] type.
+//! - **[`Point`]**: A single point represented by one [`Coordinate`]
+//! - **[`MultiPoint`]**: A collection of [`Point`]s
+//! - **[`Line`]**: A line segment represented by two [`Coordinate`]s
+//! - **[`LineString`]**: A series of contiguous line segments represented by two or more
+//!   [`Coordinate`]s
+//! - **[`MultiLineString`]**: A collection of [`LineString`]s
+//! - **[`Polygon`]**: A bounded area represented by one [`LineString`] exterior ring, and zero or
+//!   more [`LineString`] interior rings
+//! - **[`MultiPolygon`]**: A collection of [`Polygon`]s
+//! - **[`Rect`]**: An axis-aligned bounded rectangle represented by minimum and maximum
+//!   [`Coordinate`]s
+//! - **[`Triangle`]**: A bounded area represented by three [`Coordinate`] vertices
+//! - **[`GeometryCollection`]**: A collection of [`Geometry`]s
+//! - **[`Geometry`]**: An enumeration of all geometry types, excluding [`Coordinate`]
 //!
 //! # Semantics
 //!
-//! The geospatial types provided here aim to adhere to the
-//! [OpenGIS Simple feature access][OGC-SFA] standards.
-//! Thus, the types here are inter-operable with other
-//! implementations of the standards: [JTS], [geos], etc.
+//! The geospatial types provided here aim to adhere to the [OpenGIS Simple feature access][OGC-SFA]
+//! standards. Thus, the types here are inter-operable with other implementations of the standards:
+//! [JTS], [GEOS], etc.
 //!
-//! [OGC-SFA]: //www.ogc.org/standards/sfa
-//! [JTS]: //github.com/locationtech/jts
-//! [geos]: //trac.osgeo.org/geos
+//! [GeoRust]: https://georust.org
+//! [OGC-SFA]: https://www.ogc.org/standards/sfa
+//! [JTS]: https://github.com/locationtech/jts
+//! [GEOS]: https://trac.osgeo.org/geos
 extern crate num_traits;
 use num_traits::{Num, NumCast};
 

diff --git a/geo-types/src/line_string.rs b/geo-types/src/line_string.rs
@@ -2,8 +2,7 @@ use crate::{Coordinate, CoordinateType, Line, Point, Triangle};
 use std::iter::FromIterator;
 use std::ops::{Index, IndexMut};
 
-/// An ordered collection of two or more
-/// [`Coordinate`s](struct.Coordinate.html), representing a
+/// An ordered collection of two or more [`Coordinate`]s, representing a
 /// path between locations.
 ///
 /// # Semantics
@@ -40,6 +39,17 @@ use std::ops::{Index, IndexMut};
 /// ]);
 /// ```
 ///
+/// Create a `LineString` with the [`line_string!`] macro:
+///
+/// ```
+/// use geo_types::line_string;
+///
+/// let line_string = line_string![
+///     (x: 0., y: 0.),
+///     (x: 10., y: 0.),
+/// ];
+/// ```
+///
 /// Converting a `Vec` of `Coordinate`-like things:
 ///
 /// ```

diff --git a/geo-types/src/point.rs b/geo-types/src/point.rs
@@ -4,8 +4,8 @@ use std::ops::{Add, Div, Mul, Neg, Sub};
 
 /// A single point in 2D space.
 ///
-/// Points can be created using the `new(x, y)` constructor,
-/// the `point!` macro, or from a `Coordinate`, two-element
+/// Points can be created using the [`Point::new`] constructor,
+/// the [`point!`] macro, or from a `Coordinate`, two-element
 /// tuples, or arrays – see the `From` impl section for a
 /// complete list.
 ///

diff --git a/geo-types/src/polygon.rs b/geo-types/src/polygon.rs
@@ -7,6 +7,8 @@ use num_traits::{Float, Signed};
 /// [`LineString`]. It may contain zero or more holes (_interior rings_), also
 /// represented by `LineString`s.
 ///
+/// A `Polygon` can be created with the [`Polygon::new`] constructor or the [`polygon!`] macro.
+///
 /// # Semantics
 ///
 /// The _boundary_ of the polygon is the union of the