docs: Improve docs for Point and Vec2

This adds some cross-linking as well as a couple of additional
doc tests.

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()

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,16 +62,27 @@ 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
     }
 
     /// 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