From c1ec00cfe74073605f16c29f188120d81011994b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= Date: Thu, 24 Mar 2016 19:04:01 +0100 Subject: [PATCH] Complete the documentation. --- README.md | 14 +++++++------- src/lib.rs | 14 +++++++------- src/structs/dmat.rs | 8 ++++++-- src/structs/dmat_macros.rs | 4 +++- src/structs/dvec.rs | 2 -- src/structs/pnt.rs | 2 -- src/structs/quat.rs | 2 -- src/structs/rot.rs | 2 -- src/structs/rot_macros.rs | 1 + src/structs/vec.rs | 2 -- src/structs/vec_macros.rs | 11 +++++++---- 11 files changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 718350af..aa735021 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,12 @@ nalgebra * real time computer graphics. * real time computer physics. -An on-line version of this documentation is available [here](http://nalgebra.org). +An on-line version of this documentation is available [here](http://nalgebra.org/doc/nalgebra). ## Using **nalgebra** -All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`. -This module re-exports everything and includes free functions for all traits methods doing -out-of-place modifications. +All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`. This +module re-exports everything and includes free functions for all traits methods performing +out-of-place operations. * You can import the whole prelude using: @@ -46,12 +46,12 @@ an optimized set of tools for computer graphics and physics. Those features incl * Vectors with predefined static sizes: `Vec1`, `Vec2`, `Vec3`, `Vec4`, `Vec5`, `Vec6`. * Vector with a user-defined static size: `VecN`. -* Points with static sizes: ``Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`. +* Points with static sizes: `Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`. * Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `. * Rotation matrices: `Rot2`, `Rot3` * Quaternions: `Quat`, `UnitQuat`. -* Isometries (translation * rotation): `Iso2`, `Iso3` -* Similarity transformations (translation * rotation * uniform scale): `Sim2`, `Sim3`. +* Isometries (translation ⨯ rotation): `Iso2`, `Iso3` +* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`. * 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`. * Dynamically sized heap-allocated vector: `DVec`. * Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`. diff --git a/src/lib.rs b/src/lib.rs index 706d8b40..d5af670a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,16 +3,16 @@ **nalgebra** is a low-dimensional linear algebra library written for Rust targeting: -* general-purpose linear algebra (still lacks a lot of features…). +* low-dimensional general-purpose linear algebra (still lacks a lot of features…). * real time computer graphics. * real time computer physics. -An on-line version of this documentation is available [here](http://nalgebra.org). +An on-line version of this documentation is available [here](http://nalgebra.org/doc/nalgebra). ## Using **nalgebra** -All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`. -This module re-exports everything and includes free functions for all traits methods doing -out-of-place modifications. +All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`. This +module re-exports everything and includes free functions for all traits methods performing +out-of-place operations. * You can import the whole prelude using: @@ -47,8 +47,8 @@ an optimized set of tools for computer graphics and physics. Those features incl * Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `. * Rotation matrices: `Rot2`, `Rot3` * Quaternions: `Quat`, `UnitQuat`. -* Isometries (translation * rotation): `Iso2`, `Iso3` -* Similarity transformations (translation * rotation * uniform scale): `Sim2`, `Sim3`. +* Isometries (translation ⨯ rotation): `Iso2`, `Iso3` +* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`. * 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`. * Dynamically sized heap-allocated vector: `DVec`. * Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`. diff --git a/src/structs/dmat.rs b/src/structs/dmat.rs index 345c0742..36b3df4b 100644 --- a/src/structs/dmat.rs +++ b/src/structs/dmat.rs @@ -1,7 +1,5 @@ //! Matrix with dimensions unknown at compile-time. -#![allow(missing_docs)] // we hide doc to not have to document the $trhs double dispatch trait. - use std::cmp; use std::mem; use std::iter::repeat; @@ -131,6 +129,7 @@ impl DMat { dmat_impl!(DMat, DVec); +/// A stack-allocated dynamically sized matrix with at most one row and column. pub struct DMat1 { nrows: usize, ncols: usize, @@ -141,6 +140,7 @@ small_dmat_impl!(DMat1, DVec1, 1, 0); small_dmat_from_impl!(DMat1, 1, ::zero()); +/// A stack-allocated dynamically sized square or rectangular matrix with at most 2 rows and columns. pub struct DMat2 { nrows: usize, ncols: usize, @@ -153,6 +153,7 @@ small_dmat_from_impl!(DMat2, 2, ::zero(), ::zero(), ::zero(), ::zero()); +/// A stack-allocated dynamically sized square or rectangular matrix with at most 3 rows and columns. pub struct DMat3 { nrows: usize, ncols: usize, @@ -167,6 +168,7 @@ small_dmat_from_impl!(DMat3, 3, ::zero(), ::zero(), ::zero(), ::zero(), ::zero(), ::zero()); +/// A stack-allocated dynamically sized square or rectangular matrix with at most 4 rows and columns. pub struct DMat4 { nrows: usize, ncols: usize, @@ -183,6 +185,7 @@ small_dmat_from_impl!(DMat4, 4, ::zero(), ::zero(), ::zero(), ::zero(), ::zero(), ::zero(), ::zero(), ::zero()); +/// A stack-allocated dynamically sized square or rectangular matrix with at most 5 rows and columns. pub struct DMat5 { nrows: usize, ncols: usize, @@ -201,6 +204,7 @@ small_dmat_from_impl!(DMat5, 5, ::zero(), ::zero(), ::zero(), ::zero(), ::zero() ::zero(), ::zero(), ::zero(), ::zero(), ::zero()); +/// A stack-allocated dynamically sized square or rectangular matrix with at most 6 rows and columns. pub struct DMat6 { nrows: usize, ncols: usize, diff --git a/src/structs/dmat_macros.rs b/src/structs/dmat_macros.rs index 4ec9c5ef..4891fb3a 100644 --- a/src/structs/dmat_macros.rs +++ b/src/structs/dmat_macros.rs @@ -19,6 +19,7 @@ macro_rules! dmat_impl( self.mij.iter().all(|e| e.is_zero()) } + /// Set this matrix components to zero. #[inline] pub fn reset(&mut self) { for mij in self.mij.iter_mut() { @@ -881,7 +882,8 @@ macro_rules! small_dmat_from_impl( } } - impl $dmat { + impl $dmat { + /// Creates a new matrix with uninitialized components (with `mem::uninitialized()`). #[inline] pub unsafe fn new_uninitialized(nrows: usize, ncols: usize) -> $dmat { assert!(nrows <= $dim); diff --git a/src/structs/dvec.rs b/src/structs/dvec.rs index de774271..e40e54aa 100644 --- a/src/structs/dvec.rs +++ b/src/structs/dvec.rs @@ -1,7 +1,5 @@ //! Vector with dimensions unknown at compile-time. -#![allow(missing_docs)] // we hide doc to not have to document the $trhs double dispatch trait. - use std::slice::{Iter, IterMut}; use std::iter::{FromIterator, IntoIterator}; use std::iter::repeat; diff --git a/src/structs/pnt.rs b/src/structs/pnt.rs index b7524246..db10db23 100644 --- a/src/structs/pnt.rs +++ b/src/structs/pnt.rs @@ -1,7 +1,5 @@ //! Points with dimension known at compile-time. -#![allow(missing_docs)] // we allow missing to avoid having to document the point components. - use std::mem; use std::slice::{Iter, IterMut}; use std::iter::{Iterator, FromIterator, IntoIterator}; diff --git a/src/structs/quat.rs b/src/structs/quat.rs index d3a3485e..6c06817a 100644 --- a/src/structs/quat.rs +++ b/src/structs/quat.rs @@ -1,7 +1,5 @@ //! Quaternion definition. -#![allow(missing_docs)] // we allow missing to avoid having to document the dispatch trait. - use std::mem; use std::slice::{Iter, IterMut}; use std::ops::{Add, Sub, Mul, Div, Neg, Index, IndexMut}; diff --git a/src/structs/rot.rs b/src/structs/rot.rs index b3a2791e..06b013dd 100644 --- a/src/structs/rot.rs +++ b/src/structs/rot.rs @@ -1,7 +1,5 @@ //! Rotations matrices. -#![allow(missing_docs)] - use std::ops::{Mul, Neg, Index}; use rand::{Rand, Rng}; use num::{Zero, One}; diff --git a/src/structs/rot_macros.rs b/src/structs/rot_macros.rs index a9c38326..25e9ba8d 100644 --- a/src/structs/rot_macros.rs +++ b/src/structs/rot_macros.rs @@ -3,6 +3,7 @@ macro_rules! submat_impl( ($t: ident, $submat: ident) => ( impl $t { + /// This rotation's underlying matrix. #[inline] pub fn submat<'r>(&'r self) -> &'r $submat { &self.submat diff --git a/src/structs/vec.rs b/src/structs/vec.rs index 6ac503f1..01015cf4 100644 --- a/src/structs/vec.rs +++ b/src/structs/vec.rs @@ -1,7 +1,5 @@ //! Vectors with dimension known at compile-time. -#![allow(missing_docs)] // we allow missing to avoid having to document the dispatch traits. - use std::ops::{Add, Sub, Mul, Div, Neg, Index, IndexMut}; use std::mem; use std::slice::{Iter, IterMut}; diff --git a/src/structs/vec_macros.rs b/src/structs/vec_macros.rs index e358a226..1accc4d7 100644 --- a/src/structs/vec_macros.rs +++ b/src/structs/vec_macros.rs @@ -278,6 +278,7 @@ macro_rules! dim_impl( macro_rules! container_impl( ($t: ident) => ( impl $t { + /// The dimension of this entity. #[inline] pub fn len(&self) -> usize { Dim::dim(None::<$t>) @@ -291,18 +292,18 @@ macro_rules! basis_impl( impl> Basis for $t { #[inline] fn canonical_basis) -> bool>(mut f: F) { - for i in 0..$dim { + for i in 0 .. $dim { if !f(Basis::canonical_basis_element(i).unwrap()) { return } } } #[inline] fn orthonormal_subspace_basis) -> bool>(n: &$t, mut f: F) { - // compute the basis of the orthogonal subspace using Gram-Schmidt - // orthogonalization algorithm + // Compute the basis of the orthogonal subspace using Gram-Schmidt + // orthogonalization algorithm. let mut basis: Vec<$t> = Vec::new(); - for i in 0..$dim { + for i in 0 .. $dim { let mut basis_element : $t = ::zero(); unsafe { @@ -743,6 +744,7 @@ macro_rules! transform_impl( macro_rules! vec_as_pnt_impl( ($tv: ident, $t: ident, $($compN: ident),+) => ( impl $tv { + /// Converts this vector to a point. #[inline] pub fn to_pnt(self) -> $t { $t::new( @@ -750,6 +752,7 @@ macro_rules! vec_as_pnt_impl( ) } + /// Reinterprets this vector as a point. #[inline] pub fn as_pnt(&self) -> &$t { unsafe {