refactor!: move trait + add proper docs (#7)

README.md

@@ -24,9 +24,9 @@ fn main() {
     let points = points![f64, (0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
 
     // low-quality simplification (fast)
-    let new_points = simplify(points, 1, false);
+    let new_points = simplify(points, 1.0, false);
     // low-quality simplification (slower)
-    let new_points = simplify(points, 1, true);
+    let new_points = simplify(points, 1.0, true);
 }
 ```
 

src/lib.rs

@@ -1,17 +1,41 @@
-use traits::ExtendedNumOps;
+#![warn(missing_docs)]
+#![warn(rustdoc::missing_doc_code_examples)]
+#![doc = include_str!("../README.md")]
+
+pub use traits::ExtendedNumOps;
 
 #[cfg(feature = "tests")]
 use serde::{Deserialize, Serialize};
 
-pub mod traits;
-
+mod traits;
+
+/// A two-diemensional point, where the value of each coordinate must implement the
+/// [ExtendedNumOps] trait.
+///
+/// Example:
+/// ```
+/// use simplify_polyline::*;
+///
+/// let point = Point::<f64> { x: 1.0, y: 1.0 };
+/// ```
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "tests", derive(Serialize, Deserialize))]
 pub struct Point<T: ExtendedNumOps> {
+    /// The x coordinate value.
     pub x: T,
+    /// The y coordinate value.
     pub y: T,
 }
 
+/// Creates a [Point] struct, used for input and output for [simplify]. A type should be specified
+/// as the first argument that implements the [ExtendedNumOps] trait.
+///
+/// Example
+/// ```
+/// use simplify_polyline::*;
+///
+/// let point = point!(f64, 1.0, 1.0);
+/// ```
 #[macro_export]
 macro_rules! point {
     ($t:ty, $x:expr,$y:expr) => {
@@ -22,6 +46,17 @@ macro_rules! point {
     };
 }
 
+/// Creates a &[[Point]] array, used for  used for input and output for [simplify]. A type should
+/// be specified as the first argument that implements the [ExtendedNumOps] trait. Point values
+/// should be specified as length-2 tuples, where each value matches the input type, in (x, y)
+/// order.
+///
+/// Example
+/// ```
+/// use simplify_polyline::*;
+///
+/// let points = points![f64, (1.0, 1.0), (2.0, 2.0), (3.0, 3.0)];
+/// ```
 #[macro_export]
 macro_rules! points {
     ($t: ty, $(($x:expr,$y:expr)),*) => {
@@ -114,6 +149,18 @@ fn simplify_douglas_peucker<T: ExtendedNumOps>(points: &[Point<T>], tolerance: T
     simplified
 }
 
+/// Simplifies a polyline within a given tolerance.
+///
+///
+/// # Arguments
+///
+/// - `tolerance`: A distance measurement used for both radial distance and Douglas–Peucker -- the
+/// higher the tolerance, the more points will be removed from the polyline.
+/// - `high_quality`: Controls the algorithm(s) to be used in simplification
+///   - `true`: this will take the entire array of points and simplify using the Douglas–Peucker
+///     algorithm.
+///   - `false`: the list of points are first filtered using a simple radial distance algorithm,
+///     and then passed to the the Douglas-Peucker algorithm for final simplification.
 pub fn simplify<T: ExtendedNumOps>(
     points: &[Point<T>],
     tolerance: f64,

src/traits.rs

@@ -1,5 +1,6 @@
 use num_traits::{FromPrimitive, Num, NumAssign};
 
+/// Required traits a number type must implement to be used with [simplify](crate::simplify).
 pub trait ExtendedNumOps: Num + Clone + Copy + NumAssign + PartialOrd + FromPrimitive {}
 
 macro_rules! impl_extended_num_ops {