Improve cross-linking and cross-referencing in docs.

nalgebra-glm/src/geometric.rs

@@ -9,6 +9,10 @@ pub fn cross<N: Number, D: Dimension>(x: &TVec3<N>, y: &TVec3<N>) -> TVec3<N> {
 }
 
 /// The distance between two points.
+///
+/// # See also:
+///
+/// * [`distance2`](fn.distance2.html)
 pub fn distance<N: Real, D: Dimension>(p0: &TVec<N, D>, p1: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
    (p1 - p0).norm()
@@ -31,12 +35,28 @@ pub fn faceforward<N: Number, D: Dimension>(n: &TVec<N, D>, i: &TVec<N, D>, nref
 }
 
 /// The magnitude of a vector.
+///
+/// A synonym for [`magnitude`](fn.magnitude.html).
+///
+/// # See also:
+///
+/// * [`length2`](fn.length2.html)
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude2`](fn.magnitude2.html)
 pub fn length<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     x.norm()
 }
 
 /// The magnitude of a vector.
+///
+/// A wrapper around [`nalgebra::norm`](../nalgebra/fn.norm.html).
+///
+/// # See also:
+///
+/// * [`length`](fn.length.html)
+/// * [`magnitude2`](fn.magnitude2.html)
+/// * [`nalgebra::norm`](../nalgebra/fn.norm.html)
 pub fn magnitude<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     x.norm()
@@ -68,4 +88,4 @@ pub fn refract_vec<N: Real, D: Dimension>(i: &TVec<N, D>, n: &TVec<N, D>, eta: N
     else {
         i * eta - n * (eta * dot(n, i) + k.sqrt())
     }
-}
+}

nalgebra-glm/src/gtx/norm.rs

@@ -4,6 +4,10 @@ use traits::{Alloc, Dimension};
 use aliases::TVec;
 
 /// The squared distance between two points.
+///
+/// # See also:
+///
+/// * [`distance`](fn.distance.html)
 pub fn distance2<N: Real, D: Dimension>(p0: &TVec<N, D>, p1: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     (p1 - p0).norm_squared()
@@ -34,12 +38,32 @@ pub fn l2_norm<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
 }
 
 /// The squared magnitude of `x`.
+///
+/// A synonym for [`magnitude2`](fn.magnitude2.html).
+///
+/// # See also:
+///
+/// * [`distance`](fn.distance.html)
+/// * [`distance2`](fn.distance2.html)
+/// * [`length`](fn.length.html)
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude2`](fn.magnitude2.html)
 pub fn length2<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     x.norm_squared()
 }
 
 /// The squared magnitude of `x`.
+///
+/// A wrapper around [`nalgebra::norm_squared`](../nalgebra/fn.norm_squared.html).
+///
+/// # See also:
+///
+/// * [`distance`](fn.distance.html)
+/// * [`distance2`](fn.distance2.html)
+/// * [`length2`](fn.length2.html)
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`nalgebra::norm_squared`](../nalgebra/fn.norm_squared.html)
 pub fn magnitude2<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     x.norm_squared()

nalgebra-glm/src/lib.rs

@@ -38,7 +38,7 @@
     * All function names use `snake_case`, which is the Rust convention.
     * All type names use `CamelCase`, which is the Rust convention.
     * All function arguments, except for scalars, are all passed by-reference.
-    * The most generic vector and matrix types are `TMat` and `TVec` instead of `mat` and `vec`.
+    * The most generic vector and matrix types are [`TMat`](type.TMat.html) and [`TVec`](type.TVec.html) instead of `mat` and `vec`.
     * Some feature are not yet implemented and should be added in the future. In particular, no packing
     functions are available.
     * A few features are not implemented and will never be. This includes functions related to color
@@ -47,17 +47,17 @@
 
     In addition, because Rust does not allows function overloading, all functions must be given a unique name.
     Here are a few rules chosen arbitrarily for **nalgebra-glm**:
-    * Functions operating in 2d will usually end with the `2d` suffix, e.g., `glm::rotade2d` is for 2D while `glm::rotate` is for 3D.
+    * Functions operating in 2d will usually end with the `2d` suffix, e.g., [`glm::rotate2d`](fn.rotate2d.html) is for 2D while [`glm::rotate`](fn.rotate.html) is for 3D.
-    * Functions operating on vector will often end with the `_vec` suffix, possibly followed by the dimension of vector, e.g., `glm::rotate_vec2`.
+    * Functions operating on vectors will often end with the `_vec` suffix, possibly followed by the dimension of vector, e.g., [`glm::rotate_vec2`](fn.rotate_vec2.html).
-    * Every function related to quaternions start with the `quat_` prefix, e.g., `glm::quat_dot(q1, q2)`.
+    * Every function related to quaternions start with the `quat_` prefix, e.g., [`glm::quat_dot(q1, q2)`](fn.quat_dot.html).
     * All the conversion functions have unique names as described [below](#conversions).
     ### Vector and matrix construction
     Vectors, matrices, and quaternions can be constructed using several approaches:
-    * Using functions with the same name as their type in lower-case. For example `glm::vec3(x, y, z)` will create a 3D vector.
+    * Using functions with the same name as their type in lower-case. For example [`glm::vec3(x, y, z)`](fn.vec3.html) will create a 3D vector.
-    * Using the `::new` constructor. For example `Vec3::new(x, y, z)` will create a 3D vector.
+    * Using the `::new` constructor. For example [`Vec3::new(x, y, z)`](../nalgebra/base/type.MatrixMN.html#method.new-27) will create a 3D vector.
-    * Using the functions prefixed by `make_` to build a vector a matrix from a slice. For example `glm::make_vec3(&[x, y, z])` will create a 3D vector.
+    * Using the functions prefixed by `make_` to build a vector a matrix from a slice. For example [`glm::make_vec3(&[x, y, z])`](fn.make_vec3.html) will create a 3D vector.
-    Keep in mind that constructing a matrix using this type of functions require its components to be arrange in column-major order on the slice.
+    Keep in mind that constructing a matrix using this type of functions require its components to be arranged in column-major order on the slice.
-    * Using a geometric construction function. For example `glm::rotation(angle, axis)` will build a 4x4 homogeneous rotation matrix from an angle (in radians) and an axis.
+    * Using a geometric construction function. For example [`glm::rotation(angle, axis)`](fn.rotation.html) will build a 4x4 homogeneous rotation matrix from an angle (in radians) and an axis.
     * Using swizzling and conversions as described in the next sections.
     ### Swizzling
     Vector swizzling is a native feature of **nalgebra** itself. Therefore, you can use it with all
@@ -75,11 +75,11 @@
     It is often useful to convert one algebraic type to another. There are two main approaches for converting
     between types in `nalgebra-glm`:
     * Using function with the form `type1_to_type2` in order to convert an instance of `type1` into an instance of `type2`.
-    For example `glm::mat3_to_mat4(m)` will convert the 3x3 matrix `m` to a 4x4 matrix by appending one column on the right
+    For example [`glm::mat3_to_mat4(m)`](fn.mat3_to_mat4.html) will convert the 3x3 matrix `m` to a 4x4 matrix by appending one column on the right
     and one row on the left. Those now row and columns are filled with 0 except for the diagonal element which is set to 1.
-    * Using one of the `convert`, `try_convert`, or `convert_unchecked` functions.
+    * Using one of the [`convert`](fn.convert.html), [`try_convert`](fn.try_convert.html), or [`convert_unchecked`](fn.convert_unchecked.html) functions.
     These functions are directly re-exported from nalgebra and are extremely versatile:
-        1. The `convert` function can convert any type (especially geometric types from nalgebra like `Isometry3`) into another algebraic type which equivalent but more general. For example,
+        1. The `convert` function can convert any type (especially geometric types from nalgebra like `Isometry3`) into another algebraic type which is equivalent but more general. For example,
     `let sim: Similarity3<_> = na::convert(isometry)` will convert an `Isometry3` into a `Similarity3`.
     In addition, `let mat: Mat4 = glm::convert(isometry)` will convert an `Isometry3` to a 4x4 matrix. This will also convert the scalar types,
     therefore: `let mat: DMat4 = glm::convert(m)` where `m: Mat4` will work. However, conversion will not work the other way round: you

src/base/dimension.rs

@@ -209,6 +209,7 @@ pub trait NamedDim: Sized + Any + Unsigned {
     type Name: DimName<Value = Self>;
 }
 
+/// A type level dimension with a value of `1`.
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 pub struct U1;
@@ -246,6 +247,7 @@ impl NamedDim for typenum::U1 {
 
 macro_rules! named_dimension(
     ($($D: ident),* $(,)*) => {$(
+        /// A type level dimension.
         #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
         #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
         pub struct $D;

src/lib.rs

@@ -161,18 +161,33 @@ pub fn id() -> Id {
 }
 
 /// Gets the multiplicative identity element.
+///
+/// # See also:
+///
+/// * [`origin`](../nalgebra/fn.origin.html)
+/// * [`zero`](fn.zero.html)
 #[inline]
 pub fn one<T: Identity<Multiplicative>>() -> T {
     T::identity()
 }
 
 /// Gets the additive identity element.
+///
+/// # See also:
+///
+/// * [`one`](fn.one.html)
+/// * [`origin`](../nalgebra/fn.origin.html)
 #[inline]
 pub fn zero<T: Identity<Additive>>() -> T {
     T::identity()
 }
 
 /// Gets the origin of the given point.
+///
+/// # See also:
+///
+/// * [`one`](fn.one.html)
+/// * [`zero`](fn.zero.html)
 #[inline]
 pub fn origin<P: EuclideanSpace>() -> P {
     P::origin()
@@ -375,12 +390,20 @@ pub fn partial_sort2<'a, T: PartialOrd>(a: &'a T, b: &'a T) -> Option<(&'a T, &'
  */
 
 /// Tries to gets an inverted copy of a square matrix.
+///
+/// # See also:
+///
+/// * [`inverse`](fn.inverse.html)
 #[inline]
 pub fn try_inverse<M: AlgaSquareMatrix>(m: &M) -> Option<M> {
     m.try_inverse()
 }
 
 /// Computes the multiplicative inverse of an (always invertible) algebraic entity.
+///
+/// # See also:
+///
+/// * [`try_inverse`](fn.try_inverse.html)
 #[inline]
 pub fn inverse<M: Inverse<Multiplicative>>(m: &M) -> M {
     m.inverse()
@@ -407,24 +430,49 @@ pub fn angle<V: InnerSpace>(a: &V, b: &V) -> V::Real {
  */
 
 /// Computes the L2 (euclidean) norm of a vector.
+///
+/// # See also:
+///
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude_squared`](fn.magnitude_squared.html)
+/// * [`norm_squared`](fn.norm_squared.html)
 #[inline]
 pub fn norm<V: NormedSpace>(v: &V) -> V::Field {
     v.norm()
 }
 
 /// Computes the squared L2 (euclidean) norm of the vector `v`.
+///
+/// # See also:
+///
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude_squared`](fn.magnitude_squared.html)
+/// * [`norm`](fn.norm.html)
 #[inline]
 pub fn norm_squared<V: NormedSpace>(v: &V) -> V::Field {
     v.norm_squared()
 }
 
-/// A synonym function for `norm()` aka length.
+/// A synonym for [`norm`](fn.norm.html), aka length.
+///
+/// # See also:
+///
+/// * [`magnitude_squared`](fn.magnitude_squared.html)
+/// * [`norm`](fn.norm.html)
+/// * [`norm_squared`](fn.norm_squared.html)
 #[inline]
 pub fn magnitude<V: NormedSpace>(v: &V) -> V::Field {
     v.norm()
 }
 
-/// A synonym function for `norm_squared()` aka length squared.
+/// A synonym for [`norm_squared`](fn.norm_squared.html),
+///  aka length squared.
+///
+/// # See also:
+///
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`norm`](fn.norm.html)
+/// * [`norm_squared`](fn.norm_squared.html)
 #[inline]
 pub fn magnitude_squared<V: NormedSpace>(v: &V) -> V::Field {
     v.norm_squared()
@@ -448,18 +496,33 @@ pub fn try_normalize<V: NormedSpace>(v: &V, min_norm: V::Field) -> Option<V> {
  *
  */
 /// The center of two points.
+///
+/// # See also:
+///
+/// * [distance](fn.distance.html)
+/// * [distance_squared](fn.distance_squared.html)
 #[inline]
 pub fn center<P: EuclideanSpace>(p1: &P, p2: &P) -> P {
     P::from_coordinates((p1.coordinates() + p2.coordinates()) * convert(0.5))
 }
 
 /// The distance between two points.
+///
+/// # See also:
+///
+/// * [center](fn.center.html)
+/// * [distance_squared](fn.distance_squared.html)
 #[inline]
 pub fn distance<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
     (p2.coordinates() - p1.coordinates()).norm()
 }
 
 /// The squared distance between two points.
+///
+/// # See also:
+///
+/// * [center](fn.center.html)
+/// * [distance](fn.distance.html)
 #[inline]
 pub fn distance_squared<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
     (p2.coordinates() - p1.coordinates()).norm_squared()
@@ -470,7 +533,15 @@ pub fn distance_squared<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
  */
 /// Converts an object from one type to an equivalent or more general one.
 ///
-/// See also `::try_convert` for conversion to more specific types.
+/// See also [`try_convert`](fn.try_convert.html) for conversion to more specific types.
+///
+/// # See also:
+///
+/// * [convert_ref](fn.convert_ref.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert](fn.try_convert.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub fn convert<From, To: SupersetOf<From>>(t: From) -> To {
     To::from_subset(&t)
@@ -478,37 +549,89 @@ pub fn convert<From, To: SupersetOf<From>>(t: From) -> To {
 
 /// Attempts to convert an object to a more specific one.
 ///
-/// See also `::convert` for conversion to more general types.
+/// See also [`convert`](fn.convert.html) for conversion to more general types.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref](fn.convert_ref.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub fn try_convert<From: SupersetOf<To>, To>(t: From) -> Option<To> {
     t.to_subset()
 }
 
-/// Indicates if `::try_convert` will succeed without actually performing the conversion.
+/// Indicates if [`try_convert`](fn.try_convert.html) will succeed without
+/// actually performing the conversion.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref](fn.convert_ref.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [try_convert](fn.try_convert.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub fn is_convertible<From: SupersetOf<To>, To>(t: &From) -> bool {
     t.is_in_subset()
 }
 
-/// Use with care! Same as `try_convert` but without any property checks.
+/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
+/// without any property checks.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref](fn.convert_ref.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert](fn.try_convert.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub unsafe fn convert_unchecked<From: SupersetOf<To>, To>(t: From) -> To {
     t.to_subset_unchecked()
 }
 
 /// Converts an object from one type to an equivalent or more general one.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert](fn.try_convert.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub fn convert_ref<From, To: SupersetOf<From>>(t: &From) -> To {
     To::from_subset(t)
 }
 
 /// Attempts to convert an object to a more specific one.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref](fn.convert_ref.html)
+/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert](fn.try_convert.html)
 #[inline]
 pub fn try_convert_ref<From: SupersetOf<To>, To>(t: &From) -> Option<To> {
     t.to_subset()
 }
 
-/// Use with care! Same as `try_convert` but without any property checks.
+/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
+/// without any property checks.
+///
+/// # See also:
+///
+/// * [convert](fn.convert.html)
+/// * [convert_ref](fn.convert_ref.html)
+/// * [is_convertible](../nalgebra/fn.is_convertible.html)
+/// * [try_convert](fn.try_convert.html)
+/// * [try_convert_ref](fn.try_convert_ref.html)
 #[inline]
 pub unsafe fn convert_ref_unchecked<From: SupersetOf<To>, To>(t: &From) -> To {
     t.to_subset_unchecked()