Module documentation updates

src/lib.rs

@@ -13,19 +13,41 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Computer graphics-centric math.
+//! A low-dimensional linear algebra library, targeted at computer graphics.
 //!
-//! This crate provides useful mathematical primitives and operations on them.
-//! It is organized into one module per primitive. The core structures are
-//! vectors and matrices. A strongly-typed interface is provided, to prevent
-//! mixing units or violating mathematical invariants.
+//! # Trait overview
 //!
-//! Transformations are not usually done directly on matrices, but go through
-//! transformation objects that can be converted to matrices. Rotations go
-//! through the `Basis` types, which are guaranteed to be orthogonal matrices.
-//! Despite this, one can directly create a limited rotation matrix using the
-//! `look_at`, `from_angle`, `from_euler`, and `from_axis_angle` methods.
-//! These are provided for convenience.
+//! In order to make a clean, composable API, we divide operations into traits
+//! that are roughly based on mathematical properties. The main ones that we
+//! concern ourselves with are listed below:
+//!
+//! - `VectorSpace`: Specifies the main operators for vectors, quaternions, and
+//!    matrices.
+//! - `InnerSpace`: For types that have a dot (or inner) product - ie. vectors or
+//!    quaternions. This also allows for the definition of operations that are
+//!    based on the dot product, like finding the magnitude or normalizing.
+//! - `EuclideanSpace`: Points in euclidean space, with an associated space of
+//!   displacement vectors.
+//! - `Matrix`: Common operations for matrices of arbitrary dimensions.
+//! - `SquareMatrix`: A special trait for matrices where the number of columns
+//!   equal the number of rows.
+//!
+//! Other traits are included for practical convenience, for example:
+//!
+//! - `Array`: For contiguous, indexable arrays of elements, specifically
+//!   vectors.
+//! - `ElementWise`: For element-wise addition, subtraction, multiplication,
+//!   division, and remainder operations.
+//!
+//! # The prelude
+//!
+//! Importing each trait individually can become a chore, so we provide a
+//! `prelude` module to allow you to import the main trait all at once. For
+//! example:
+//!
+//! ```rust
+//! use cgmath::prelude::*;
+//! ```
 
 extern crate num as rust_num;
 extern crate rustc_serialize;

src/matrix.rs

@@ -13,8 +13,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Column major, square matrix types and traits.
-
 use std::fmt;
 use std::mem;
 use std::ops::*;

src/vector.rs

@@ -13,80 +13,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Types and traits for two, three, and four-dimensional vectors.
-//!
-//! ## Working with Vectors
-//!
-//! Vectors can be created in several different ways. There is, of course, the
-//! traditional `new()` method, but unit vectors, zero vectors, and an one
-//! vector are also provided:
-//!
-//! ```rust
-//! use cgmath::{VectorSpace, Vector2, Vector3, Vector4, vec3};
-//!
-//! assert_eq!(Vector2::new(1.0f64, 0.0f64), Vector2::unit_x());
-//! assert_eq!(vec3(0.0f64, 0.0f64, 0.0f64), Vector3::zero());
-//! ```
-//!
-//! Vectors can be manipulated with typical mathematical operations (addition,
-//! subtraction, element-wise multiplication, element-wise division, negation)
-//! using the built-in operators.
-//!
-//! ```rust
-//! use cgmath::{VectorSpace, Vector2, Vector3, Vector4};
-//!
-//! let a: Vector2<f64> = Vector2::new(3.0, 4.0);
-//! let b: Vector2<f64> = Vector2::new(-3.0, -4.0);
-//!
-//! assert_eq!(a + b, Vector2::zero());
-//! assert_eq!(-(a * 2.0), Vector2::new(-6.0, -8.0));
-//!
-//! // As with Rust's `int` and `f32` types, Vectors of different types cannot
-//! // be added and so on with impunity. The following will fail to compile:
-//! // let c = a + Vector3::new(1.0, 0.0, 2.0);
-//!
-//! // Instead, we need to convert the Vector2 to a Vector3 by "extending" it
-//! // with the value for the last coordinate:
-//! let c: Vector3<f64> = a.extend(0.0) + Vector3::new(1.0, 0.0, 2.0);
-//!
-//! // Similarly, we can "truncate" a Vector4 down to a Vector3:
-//! let d: Vector3<f64> = c + Vector4::unit_x().truncate();
-//!
-//! assert_eq!(d, Vector3::new(5.0f64, 4.0f64, 2.0f64));
-//! ```
-//!
-//! Vectors also provide methods for typical operations such as
-//! [scalar multiplication](http://en.wikipedia.org/wiki/Scalar_multiplication),
-//! [dot products](http://en.wikipedia.org/wiki/Dot_product),
-//! and [cross products](http://en.wikipedia.org/wiki/Cross_product).
-//!
-//! ```rust
-//! use cgmath::{VectorSpace, InnerSpace};
-//! use cgmath::{Vector2, Vector3, Vector4};
-//!
-//! // All vectors implement the dot product as a method:
-//! let a: Vector2<f64> = Vector2::new(3.0, 6.0);
-//! let b: Vector2<f64> = Vector2::new(-2.0, 1.0);
-//! assert_eq!(a.dot(b), 0.0);
-//!
-//! // But there is also a top-level function:
-//! assert_eq!(a.dot(b), cgmath::dot(a, b));
-//!
-//! // Cross products are defined for 3-dimensional vectors:
-//! let e: Vector3<f64> = Vector3::unit_x();
-//! let f: Vector3<f64> = Vector3::unit_y();
-//! assert_eq!(e.cross(f), Vector3::unit_z());
-//! ```
-//!
-//! Several other useful methods are provided as well. Vector fields can be
-//! accessed using array syntax (i.e. `vector[0] == vector.x`), or by using
-//! the methods provided by the [`Array`](../array/trait.Array.html) trait.
-//! This trait also provides a `map()` method for applying arbitrary functions.
-//!
-//! The [`VectorSpace`](../trait.VectorSpace.html) trait presents the most
-//! general features of the vectors, while [`InnerSpace`]
-//! (../array/trait.InnerSpace.html) is more specific to Euclidean space.
-
 use std::fmt;
 use std::mem;
 use std::ops::*;