Update docs

README.md

@@ -1,9 +1,36 @@
 # `wkb`
 
-Transitory crate for reading/writing [Well-Known Binary](https://libgeos.org/specifications/wkb/).
+[![Crate][crates-badge]][crates-url]
+[![API Documentation][docs-badge]][docs-url]
 
-This is being refactored out of https://github.com/geoarrow/geoarrow-rs in the hope that it can be a standalone [georust](https://github.com/georust) repository.
+[crates-badge]: https://img.shields.io/crates/v/wkb.svg
+[crates-url]: https://crates.io/crates/wkb
+[docs-badge]: https://docs.rs/wkb/badge.svg
+[docs-url]: https://docs.rs/wkb
 
-Notes:
+A fast, freely-licensed implementation of reading and writing the [Well-Known Binary][wkb] encoding of vector geometries.
 
-- Implement M and ZM variants.
+## Features
+
+- Reading and write without copying to an intermediate representation, thanks to [`geo_traits`][geo_traits].
+- Full support for Z, M, and ZM dimension data.
+- Full support for little-endian and big-endian data, in both reading and writing.
+- MIT and Apache 2 license.
+
+[geo_traits]: https://docs.rs/geo-traits/latest/geo_traits/
+[wkb]: https://libgeos.org/specifications/wkb/
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.

src/reader/mod.rs

@@ -1,10 +1,7 @@
-//! Parse WKB buffers.
-//!
-//! Each of the data structures in this module is intended to mirror the [WKB
-//! spec](https://portal.ogc.org/files/?artifact_id=25355).
-//!
-//! Each of these data structures implement traits from [geo-traits] for interoperability. These
-//! traits are the standard way to access coordinates.
+//! Parse buffers containing WKB-encoded geometries.
+
+// Each of the data structures in this module is intended to mirror the [WKB
+// spec](https://portal.ogc.org/files/?artifact_id=25355).
 
 mod coord;
 mod geometry;
@@ -31,6 +28,24 @@ use geo_traits::GeometryTrait;
 
 use crate::error::WKBResult;
 
+/// Parse a WKB byte slice into a geometry.
+///
+/// This returns an opaque object that implements [`GeometryTrait`]. Use methods provided by
+/// [`geo_traits`] to access the underlying data.
+///
+/// The contained [dimension][geo_traits::Dimensions] will never be `Unknown`.
+///
+/// ### Performance
+///
+/// WKB is not a zero-copy format because coordinates are not 8-byte aligned and because an initial
+/// scan needs to take place to know internal buffer offsets.
+///
+/// This function does an initial pass over the WKB buffer to validate the contents and record the
+/// byte offsets for relevant coordinate slices but does not copy the underlying data to an
+/// alternate representation. This means that coordinates will **always be constant-time to
+/// access** but **not zero-copy**. This is because the raw WKB buffer is not 8-byte aligned, so
+/// when accessing a coordinate the underlying bytes need to be copied into a newly-allocated
+/// `f64`.
 pub fn read_wkb(buf: &[u8]) -> WKBResult<impl GeometryTrait<T = f64> + use<'_>> {
     Wkb::try_new(buf)
 }

src/writer/geometry.rs

@@ -10,7 +10,7 @@ use crate::Endianness;
 use geo_traits::{GeometryTrait, GeometryType};
 use std::io::Write;
 
-/// The byte length of a Geometry
+/// The number of bytes this geometry will take up when encoded as WKB
 pub fn geometry_wkb_size(geom: &impl GeometryTrait<T = f64>) -> usize {
     use GeometryType::*;
     match geom.as_type() {

src/writer/geometrycollection.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::GeometryCollectionTrait;
 use std::io::Write;
 
-/// The byte length of a GeometryCollection
+/// The number of bytes this GeometryCollection will take up when encoded as WKB
 pub fn geometry_collection_wkb_size(geom: &impl GeometryCollectionTrait<T = f64>) -> usize {
     let mut sum = 1 + 4 + 4;
 

src/writer/line.rs

@@ -30,7 +30,7 @@ impl<'a, G: LineTrait<T = f64>> LineStringTrait for LineWrapper<'a, G> {
     }
 }
 
-/// The byte length of a Line
+/// The number of bytes this Line will take up when encoded as WKB
 pub fn line_wkb_size(geom: &impl LineTrait<T = f64>) -> usize {
     line_string_wkb_size(&LineWrapper(geom))
 }

src/writer/linestring.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::LineStringTrait;
 use std::io::Write;
 
-/// The byte length of a LineString
+/// The number of bytes this LineString will take up when encoded as WKB
 pub fn line_string_wkb_size(geom: &impl LineStringTrait<T = f64>) -> usize {
     let header = 1 + 4 + 4;
     let each_coord = geom.dim().size() * 8;

src/writer/mod.rs

@@ -1,3 +1,5 @@
+//! Write geometries to Well-Known Binary encoding.
+
 mod coord;
 mod geometry;
 mod geometrycollection;

src/writer/multilinestring.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::MultiLineStringTrait;
 use std::io::Write;
 
-/// The byte length of a MultiLineString
+/// The number of bytes this MultiLineString will take up when encoded as WKB
 pub fn multi_line_string_wkb_size(geom: &impl MultiLineStringTrait<T = f64>) -> usize {
     let mut sum = 1 + 4 + 4;
     for line_string in geom.line_strings() {

src/writer/multipoint.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::MultiPointTrait;
 use std::io::Write;
 
-/// The byte length of a MultiPoint
+/// The number of bytes this MultiPoint will take up when encoded as WKB
 pub fn multi_point_wkb_size(geom: &impl MultiPointTrait<T = f64>) -> usize {
     1 + 4 + 4 + (geom.num_points() * point_wkb_size(geom.dim()))
 }

src/writer/multipolygon.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::MultiPolygonTrait;
 use std::io::Write;
 
-/// The byte length of a MultiPolygon
+/// The number of bytes this MultiPolygon will take up when encoded as WKB
 pub fn multi_polygon_wkb_size(geom: &impl MultiPolygonTrait<T = f64>) -> usize {
     let mut sum = 1 + 4 + 4;
     for polygon in geom.polygons() {

src/writer/point.rs

@@ -7,7 +7,7 @@ use core::f64;
 use geo_traits::PointTrait;
 use std::io::Write;
 
-/// The byte length of a Point
+/// The number of bytes this Point will take up when encoded as WKB
 pub fn point_wkb_size(dim: geo_traits::Dimensions) -> usize {
     let header = 1 + 4;
     let coords = dim.size() * 8;

src/writer/polygon.rs

@@ -6,7 +6,7 @@ use byteorder::{BigEndian, ByteOrder, LittleEndian, WriteBytesExt};
 use geo_traits::{LineStringTrait, PolygonTrait};
 use std::io::Write;
 
-/// The byte length of a Polygon
+/// The number of bytes this Polygon will take up when encoded as WKB
 pub fn polygon_wkb_size(geom: &impl PolygonTrait<T = f64>) -> usize {
     let mut sum = 1 + 4 + 4;
 

src/writer/rect.rs

@@ -101,7 +101,7 @@ impl<'a, G: RectTrait<T = f64>> PolygonTrait for RectWrapper<'a, G> {
     }
 }
 
-/// The byte length of a Rect
+/// The number of bytes this Rect will take up when encoded as WKB
 pub fn rect_wkb_size(geom: &impl RectTrait<T = f64>) -> usize {
     polygon_wkb_size(&RectWrapper(geom))
 }

src/writer/triangle.rs

@@ -52,7 +52,7 @@ impl<'a, G: TriangleTrait<T = f64>> PolygonTrait for TriangleWrapper<'a, G> {
     }
 }
 
-/// The byte length of a Triangle
+/// The number of bytes this Triangle will take up when encoded as WKB
 pub fn triangle_wkb_size(geom: &impl TriangleTrait<T = f64>) -> usize {
     polygon_wkb_size(&TriangleWrapper(geom))
 }