From 502830d1f987a6b8950d11021d3da2735f321fac Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Sun, 4 Aug 2024 23:34:54 +0700 Subject: [PATCH] docs: Improve docs for `Point` and `Vec2` This adds some cross-linking as well as a couple of additional doc tests. --- src/point.rs | 33 +++++++++++++++++++------- src/vec2.rs | 67 ++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 77 insertions(+), 23 deletions(-) diff --git a/src/point.rs b/src/point.rs index cd4909b4..2216adc7 100644 --- a/src/point.rs +++ b/src/point.rs @@ -64,19 +64,22 @@ impl Point { } /// Euclidean distance. + /// + /// See [`Vec2::hypot`] for the same operation on [`Vec2`]. #[inline] pub fn distance(self, other: Point) -> f64 { (self - other).hypot() } /// Squared Euclidean distance. + /// + /// See [`Vec2::hypot2`] for the same operation on [`Vec2`]. #[inline] pub fn distance_squared(self, other: Point) -> f64 { (self - other).hypot2() } - /// Returns a new `Point`, - /// with `x` and `y` rounded to the nearest integer. + /// Returns a new `Point`, with `x` and `y` [rounded] to the nearest integer. /// /// # Examples /// @@ -89,13 +92,15 @@ impl Point { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded]: f64::round #[inline] pub fn round(self) -> Point { Point::new(self.x.round(), self.y.round()) } /// Returns a new `Point`, - /// with `x` and `y` rounded up to the nearest integer, + /// with `x` and `y` [rounded up] to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -109,13 +114,15 @@ impl Point { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded up]: f64::ceil #[inline] pub fn ceil(self) -> Point { Point::new(self.x.ceil(), self.y.ceil()) } /// Returns a new `Point`, - /// with `x` and `y` rounded down to the nearest integer, + /// with `x` and `y` [rounded down] to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -129,13 +136,15 @@ impl Point { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -4.0); /// ``` + /// + /// [rounded down]: f64::floor #[inline] pub fn floor(self) -> Point { Point::new(self.x.floor(), self.y.floor()) } /// Returns a new `Point`, - /// with `x` and `y` rounded away from zero to the nearest integer, + /// with `x` and `y` [rounded away] from zero to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -149,13 +158,15 @@ impl Point { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -4.0); /// ``` + /// + /// [rounded away]: FloatExt::expand #[inline] pub fn expand(self) -> Point { Point::new(self.x.expand(), self.y.expand()) } /// Returns a new `Point`, - /// with `x` and `y` rounded towards zero to the nearest integer, + /// with `x` and `y` [rounded towards] zero to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -169,18 +180,24 @@ impl Point { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded towards]: f64::trunc #[inline] pub fn trunc(self) -> Point { Point::new(self.x.trunc(), self.y.trunc()) } - /// Is this point finite? + /// Is this point [finite]? + /// + /// [finite]: f64::is_finite #[inline] pub fn is_finite(self) -> bool { self.x.is_finite() && self.y.is_finite() } - /// Is this point NaN? + /// Is this point [`NaN`]? + /// + /// [`NaN`]: f64::is_nan #[inline] pub fn is_nan(self) -> bool { self.x.is_nan() || self.y.is_nan() diff --git a/src/vec2.rs b/src/vec2.rs index 8b148d1a..3b6b85cd 100644 --- a/src/vec2.rs +++ b/src/vec2.rs @@ -16,7 +16,7 @@ use crate::common::FloatFuncs; /// /// This is intended primarily for a vector in the mathematical sense, /// but it can be interpreted as a translation, and converted to and -/// from a point (vector relative to the origin) and size. +/// from a [`Point`] (vector relative to the origin) and [`Size`]. #[derive(Clone, Copy, Default, Debug, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] @@ -37,13 +37,13 @@ impl Vec2 { Vec2 { x, y } } - /// Convert this vector into a `Point`. + /// Convert this vector into a [`Point`]. #[inline] pub const fn to_point(self) -> Point { Point::new(self.x, self.y) } - /// Convert this vector into a `Size`. + /// Convert this vector into a [`Size`]. #[inline] pub const fn to_size(self) -> Size { Size::new(self.x, self.y) @@ -62,7 +62,7 @@ impl Vec2 { /// Cross product of two vectors. /// - /// This is signed so that (0, 1) × (1, 0) = 1. + /// This is signed so that `(0, 1) × (1, 0) = 1`. #[inline] pub fn cross(self, other: Vec2) -> f64 { self.x * other.y - self.y * other.x @@ -70,8 +70,19 @@ impl Vec2 { /// Magnitude of vector. /// - /// This is similar to `self.hypot2().sqrt()` but defers to the platform `hypot` method, which - /// in general will handle the case where `self.hypot2() > f64::MAX`. + /// This is similar to `self.hypot2().sqrt()` but defers to the platform + /// [`f64::hypot`] method, which in general will handle the case where + /// `self.hypot2() > f64::MAX`. + /// + /// See [`Point::distance`] for the same operation on [`Point`]. + /// + /// # Examples + /// + /// ``` + /// use kurbo::Vec2; + /// let v = Vec2::new(3.0, 4.0); + /// assert_eq!(v.hypot(), 5.0); + /// ``` #[inline] pub fn hypot(self) -> f64 { self.x.hypot(self.y) @@ -86,6 +97,16 @@ impl Vec2 { } /// Magnitude squared of vector. + /// + /// See [`Point::distance_squared`] for the same operation on [`Point`]. + /// + /// # Examples + /// + /// ``` + /// use kurbo::Vec2; + /// let v = Vec2::new(3.0, 4.0); + /// assert_eq!(v.hypot2(), 25.0); + /// ``` #[inline] pub fn hypot2(self) -> f64 { self.dot(self) @@ -145,17 +166,19 @@ impl Vec2 { self + t * (other - self) } - /// Returns a vector of magnitude 1.0 with the same angle as `self`; i.e. + /// Returns a vector of [magnitude] 1.0 with the same angle as `self`; i.e. /// a unit/direction vector. /// /// This produces `NaN` values when the magnitude is `0`. + /// + /// [magnitude]: Self::hypot #[inline] pub fn normalize(self) -> Vec2 { self / self.hypot() } /// Returns a new `Vec2`, - /// with `x` and `y` rounded to the nearest integer. + /// with `x` and `y` [rounded] to the nearest integer. /// /// # Examples /// @@ -168,13 +191,15 @@ impl Vec2 { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded]: f64::round #[inline] pub fn round(self) -> Vec2 { Vec2::new(self.x.round(), self.y.round()) } /// Returns a new `Vec2`, - /// with `x` and `y` rounded up to the nearest integer, + /// with `x` and `y` [rounded up] to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -188,13 +213,15 @@ impl Vec2 { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded up]: f64::ceil #[inline] pub fn ceil(self) -> Vec2 { Vec2::new(self.x.ceil(), self.y.ceil()) } /// Returns a new `Vec2`, - /// with `x` and `y` rounded down to the nearest integer, + /// with `x` and `y` [rounded down] to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -208,13 +235,15 @@ impl Vec2 { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -4.0); /// ``` + /// + /// [rounded down]: f64::floor #[inline] pub fn floor(self) -> Vec2 { Vec2::new(self.x.floor(), self.y.floor()) } /// Returns a new `Vec2`, - /// with `x` and `y` rounded away from zero to the nearest integer, + /// with `x` and `y` [rounded away] from zero to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -228,13 +257,15 @@ impl Vec2 { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -4.0); /// ``` + /// + /// [rounded away]: FloatExt::expand #[inline] pub fn expand(self) -> Vec2 { Vec2::new(self.x.expand(), self.y.expand()) } /// Returns a new `Vec2`, - /// with `x` and `y` rounded towards zero to the nearest integer, + /// with `x` and `y` [rounded towards] zero to the nearest integer, /// unless they are already an integer. /// /// # Examples @@ -248,24 +279,30 @@ impl Vec2 { /// assert_eq!(b.x, 3.0); /// assert_eq!(b.y, -3.0); /// ``` + /// + /// [rounded towards]: f64::trunc #[inline] pub fn trunc(self) -> Vec2 { Vec2::new(self.x.trunc(), self.y.trunc()) } - /// Is this Vec2 finite? + /// Is this `Vec2` finite? + /// + /// [finite]: f64::is_finite #[inline] pub fn is_finite(self) -> bool { self.x.is_finite() && self.y.is_finite() } - /// Is this Vec2 NaN? + /// Is this `Vec2` [`NaN`]? + /// + /// [`NaN`]: f64::is_nan #[inline] pub fn is_nan(self) -> bool { self.x.is_nan() || self.y.is_nan() } - /// Divides this Vec2 by a scalar. + /// Divides this `Vec2` by a scalar. /// /// Unlike the division by scalar operator, which multiplies by the /// reciprocal for performance, this performs the division