Add generated docs to Matrix, Vector and Point types

src/lib.rs

@@ -4,7 +4,6 @@ Mint - Math interoperability standard types.
 Defines basic math types useful for computer graphics.
 Designed to serve as an interoperability standard between libraries.
 */
-#![deny(missing_docs)]
 
 mod matrix;
 mod rotation;

src/matrix.rs

@@ -1,13 +1,43 @@
 use vector::{Vector2, Vector3, Vector4};
 use std::mem;
 
+macro_rules! decl_matrix_type {
+    (
+        $(#[$attr:meta])*
+        $v:vis struct $name:ident {
+            $(
+                #[doc = $field_doc:expr]
+                $field_vis:vis $field:ident: $field_ty:ident
+            ),*
+        }
+    ) => {
+        $(#[$attr])*
+        $v struct $name<T> {
+            $(
+                #[doc = $field_doc]
+                $field_vis $field: $field_ty<T>
+            ),*
+        }
+    };
+}
+
 macro_rules! matrix {
-    ($name:ident : $vec:ident[ $($field:ident[$($sub:ident),*] = $index:expr),* ] = ($inner:expr, $outer:expr)) => {
-        #[derive(Clone, Copy, Debug, Hash, PartialEq, PartialOrd, Eq, Ord)]
-        #[repr(C)]
-        #[allow(missing_docs)] //TODO: actually have docs
-        pub struct $name<T> {
-            $( pub $field : $vec<T>, )*
+    (
+        $( #[doc = $doc:expr] )*
+        $name:ident: $major_ty:ident $vec:ident[ $($field:ident[$($sub:ident),*] = $index:expr),* ] = ($inner:expr, $outer:expr)
+    ) => {
+        decl_matrix_type! {
+            $( #[doc = $doc] )*
+            #[repr(C)]
+            #[derive(Clone, Copy, Debug, Hash, PartialEq, PartialOrd, Eq, Ord)]
+            pub struct $name {
+                $(
+                    #[doc = concat!(
+                        stringify!($major_ty), " ", stringify!($index), " of the matrix.",
+                    )]
+                    pub $field: $vec
+                ),*
+            }
         }
 
         impl<T> From<[[T; $inner]; $outer]> for $name<T> {
@@ -73,56 +103,107 @@ macro_rules! turn {
     }
 }
 
-/// 2x2 row-major matrix.
-matrix!( RowMatrix2 : Vector2[x[x,y]=0,y[x,y]=1] = (2, 2));
+matrix!(
+    #[doc = "A 2×2 row-major matrix."]
+    RowMatrix2 : Row Vector2[x[x,y]=0,y[x,y]=1] = (2, 2)
+);
 turn!( RowMatrix2 : Vector2[x[x,y],y[x,y]] = ColumnMatrix2 );
-/// 2x3 row-major matrix.
-/// Useful for combining rotation, scale, and translation in 2D space.
-matrix!( RowMatrix2x3 : Vector3[x[x,y,z]=0,y[x,y,z]=1] = (3, 2));
+
+matrix!(
+    #[doc = "A 2×3 row-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 2D space."]
+    RowMatrix2x3 : Row Vector3[x[x,y,z]=0,y[x,y,z]=1] = (3, 2)
+);
 turn!( RowMatrix2x3 : Vector3[x[x,y,z],y[x,y,z]] = ColumnMatrix2x3 );
-/// 3x2 row-major matrix.
-/// Useful for combining rotation, scale, and translation in 2D space.
-matrix!( RowMatrix3x2 : Vector2[x[x,y]=0,y[x,y]=1,z[x,y]=2] = (2, 3));
+
+matrix!(
+    #[doc = "A 3×2 row-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 2D space."]
+    RowMatrix3x2 : Row Vector2[x[x,y]=0,y[x,y]=1,z[x,y]=2] = (2, 3)
+);
 turn!( RowMatrix3x2 : Vector2[x[x,y],y[x,y],z[x,y]] = ColumnMatrix3x2 );
-/// 3x3 row-major matrix.
-/// Useful for representing rotation and scale in 3D space.
-matrix!( RowMatrix3 : Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2] = (3, 3));
+
+matrix!(
+    #[doc = "A 3×3 row-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for representing rotation and scale in 3D space."]
+    RowMatrix3 : Row Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2] = (3, 3)
+);
 turn!( RowMatrix3 : Vector3[x[x,y,z],y[x,y,z],z[x,y,z]] = ColumnMatrix3 );
-/// 3x4 row-major matrix.
-/// Useful for combining rotation, scale, and translation in 3D space.
-matrix!( RowMatrix3x4 : Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2] = (4, 3));
+
+matrix!(
+    #[doc = "A 3×4 row-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 3D space."]
+    RowMatrix3x4 : Row Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2] = (4, 3)
+);
 turn!( RowMatrix3x4 : Vector4[x[x,y,z,w],y[x,y,z,w],z[x,y,z,w]] = ColumnMatrix3x4 );
-/// 4x3 row-major matrix.
-/// Useful for combining rotation, scale, and translation in 3D space.
-matrix!( RowMatrix4x3 : Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2,w[x,y,z]=3] = (3, 4));
+
+matrix!(
+    #[doc = "A 4×3 row-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 3D space."]
+    RowMatrix4x3 : Row Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2,w[x,y,z]=3] = (3, 4)
+);
 turn!( RowMatrix4x3 : Vector3[x[x,y,z],y[x,y,z],z[x,y,z],w[x,y,z]] = ColumnMatrix4x3 );
-/// 4x4 row-major matrix.
-matrix!( RowMatrix4 : Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2,w[x,y,z,w]=3] = (4, 4));
+
+matrix!(
+    #[doc = "A 4×4 row-major matrix."]
+    RowMatrix4 : Row Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2,w[x,y,z,w]=3] = (4, 4)
+);
 turn!( RowMatrix4 : Vector4[x[x,y,z,w],y[x,y,z,w],z[x,y,z,w],w[x,y,z,w]] = ColumnMatrix4 );
 
-/// 2x2 column-major matrix.
-matrix!( ColumnMatrix2 : Vector2[x[x,y]=0,y[x,y]=1] = (2, 2));
+
+matrix!(
+    #[doc = "A 2×2 column-major matrix."]
+    ColumnMatrix2 : Column Vector2[x[x,y]=0,y[x,y]=1] = (2, 2)
+);
 turn!( ColumnMatrix2 : Vector2[x[x,y],y[x,y]] = RowMatrix2 );
-/// 2x3 column-major matrix.
-/// Useful for combining rotation, scale, and translation in 2D space.
-matrix!( ColumnMatrix2x3 : Vector2[x[x,y]=0,y[x,y]=1,z[x,y]=2] = (2, 3));
+
+matrix!(
+    #[doc = "A 2×3 column-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 2D space."]
+    ColumnMatrix2x3 : Column Vector2[x[x,y]=0,y[x,y]=1,z[x,y]=2] = (2, 3)
+);
 turn!( ColumnMatrix2x3 : Vector2[x[x,y],y[x,y],z[x,y]] = RowMatrix2x3 );
-/// 3x2 column-major matrix.
-/// Useful for combining rotation, scale, and translation in 2D space.
-matrix!( ColumnMatrix3x2 : Vector3[x[x,y,z]=0,y[x,y,z]=1] = (3, 2));
+
+matrix!(
+    #[doc = "A 3×2 column-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 2D space."]
+    ColumnMatrix3x2 : Column Vector3[x[x,y,z]=0,y[x,y,z]=1] = (3, 2)
+);
 turn!( ColumnMatrix3x2 : Vector3[x[x,y,z],y[x,y,z]] = RowMatrix3x2 );
-/// 3x3 column-major matrix.
-/// Useful for representing rotation and scale in 3D space.
-matrix!( ColumnMatrix3 : Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2] = (3, 3));
+
+matrix!(
+    #[doc = "A 3×3 column-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for representing rotation and scale in 3D space."]
+    ColumnMatrix3 : Column Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2] = (3, 3)
+);
 turn!( ColumnMatrix3 : Vector3[x[x,y,z],y[x,y,z],z[x,y,z]] = RowMatrix3 );
-/// 3x4 column-major matrix.
-/// Useful for combining rotation, scale, and translation in 3D space.
-matrix!( ColumnMatrix3x4 : Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2,w[x,y,z]=3] = (3, 4));
+
+matrix!(
+    #[doc = "A 3×4 column-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 3D space."]
+    ColumnMatrix3x4 : Column Vector3[x[x,y,z]=0,y[x,y,z]=1,z[x,y,z]=2,w[x,y,z]=3] = (3, 4)
+);
 turn!( ColumnMatrix3x4 : Vector3[x[x,y,z],y[x,y,z],z[x,y,z],w[x,y,z]] = RowMatrix3x4 );
-/// 4x3 column-major matrix.
-/// Useful for combining rotation, scale, and translation in 3D space.
-matrix!( ColumnMatrix4x3 : Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2] = (4, 3));
+
+matrix!(
+    #[doc = "A 4×3 column-major matrix."]
+    #[doc = "\n"]
+    #[doc = "Useful for combining rotation, scale, and translation in 3D space."]
+    ColumnMatrix4x3 : Column Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2] = (4, 3)
+);
 turn!( ColumnMatrix4x3 : Vector4[x[x,y,z,w],y[x,y,z,w],z[x,y,z,w]] = RowMatrix4x3 );
-/// 4x4 column-major matrix.
-matrix!( ColumnMatrix4 : Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2,w[x,y,z,w]=3] = (4, 4));
+
+matrix!(
+    #[doc = "A 4×4 column-major matrix."]
+    ColumnMatrix4 : Column Vector4[x[x,y,z,w]=0,y[x,y,z,w]=1,z[x,y,z,w]=2,w[x,y,z,w]=3] = (4, 4)
+);
 turn!( ColumnMatrix4 : Vector4[x[x,y,z,w],y[x,y,z,w],z[x,y,z,w],w[x,y,z,w]] = RowMatrix4 );

src/rotation.rs

@@ -1,7 +1,6 @@
 use std::marker::PhantomData;
 use vector::Vector3;
 
-
 /// Standard quaternion represented by the scalar and vector parts.
 /// Useful for representing rotation in 3D space.
 /// Corresponds to a right-handed rotation matrix.

src/vector.rs

@@ -1,12 +1,5 @@
-macro_rules! vec {
-    ($name:ident [ $($field:ident = $index:expr),* ] = $fixed:ty) => {
-        #[derive(Clone, Copy, Debug, Hash, PartialEq, PartialOrd, Eq, Ord)]
-        #[repr(C)]
-        #[allow(missing_docs)] //TODO: actually have docs
-        pub struct $name<T> {
-            $( pub $field : T, )*
-        }
-
+macro_rules! vec_methods {
+    (doc($sname:expr) $name:ident ($dim:expr) [ $($field:ident = $index:expr),* ] = $fixed:ty) => {
         impl<T> From<$fixed> for $name<T> {
             fn from([$($field),*]: $fixed) -> Self {
                 $name {
@@ -28,7 +21,15 @@ macro_rules! vec {
         }
 
         impl<T: Clone> $name<T> {
-            #[allow(missing_docs)]
+            #[doc = "Constructs a `"]
+            #[doc = $sname]
+            #[doc = "` from the first "]
+            #[doc = $dim]
+            #[doc = " elements of `slice`.\n"]
+            #[doc = "# Panics\n"]
+            #[doc = "This method will panic if `slice.len()` is smaller than "]
+            #[doc = $dim]
+            #[doc = "."]
             pub fn from_slice(slice: &[T]) -> Self {
                 $name {
                     $(
@@ -40,6 +41,48 @@ macro_rules! vec {
     }
 }
 
+macro_rules! decl_vector_type {
+    (
+        $(#[$attr:meta])*
+        $v:vis struct $name:ident<$generic:ident> {
+            $(
+                $(#[doc = $doc:expr])*
+                $fvis:vis $field:ident : $field_ty:ident
+            ),*
+        }
+    ) => {
+        $(#[$attr])*
+        $v struct $name<$generic> {
+            $(
+                $(#[doc = $doc])*
+                $fvis $field: $field_ty
+            ),*
+        }
+    };
+}
+
+macro_rules! vec {
+    (
+        $(#[doc = $doc:expr])*
+        $name:ident ($dim:expr) [ $($field:ident = $index:expr),* ] = $fixed:ty
+    ) => {
+        decl_vector_type! {
+            $(#[doc = $doc])*
+            #[derive(Clone, Copy, Debug, Hash, PartialEq, PartialOrd, Eq, Ord)]
+            #[repr(C)]
+            pub struct $name<T> {
+                $(
+                    #[doc = concat!(
+                        "The ", stringify!($field), " component of the `", stringify!($name), "`."
+                    )]
+                    pub $field: T
+                ),*
+            }
+        }
+        vec_methods!(doc(stringify!($name)) $name (stringify!($dim)) [ $($field = $index),* ] = $fixed);
+    }
+}
+
 macro_rules! from {
     ($name:ident [ $($field:ident),* ] = $other:ident) => {
         impl<T> From<$other<T>> for $name<T> {
@@ -54,12 +97,27 @@ macro_rules! from {
     }
 }
 
-vec!( Vector2 [x=0, y=1] = [T; 2] );
+vec!(
+    #[doc = "A vector representing direction and magnitude in 2D space."]
+    Vector2 (2) [x=0, y=1] = [T; 2]
+);
 from!( Vector2 [x,y] = Point2 );
-vec!( Vector3 [x=0, y=1, z=2] = [T; 3] );
+vec!(
+    #[doc = "A vector representing direction and magnitude in 3D space."]
+    Vector3 (3) [x=0, y=1, z=2] = [T; 3]
+);
 from!( Vector3 [x,y,z] = Point3 );
-vec!( Vector4 [x=0, y=1, z=2, w=3] = [T; 4] );
-vec!( Point2 [x=0, y=1] = [T; 2] );
+vec!(
+    #[doc = "A vector representing direction and magnitude in 4D space."]
+    Vector4 (4) [x=0, y=1, z=2, w=3] = [T; 4]
+);
+vec!(
+    #[doc = "A point representing a position in 2D space."]
+    Point2 (2) [x=0, y=1] = [T; 2]
+);
 from!( Point2 [x,y] = Vector2 );
-vec!( Point3 [x=0, y=1, z=2] = [T; 3] );
+vec!(
+    #[doc = "A point representing a position in 3D space."]
+    Point3 (3) [x=0, y=1, z=2] = [T; 3]
+);
 from!( Point3 [x,y,z] = Vector3 );