Reorganize matrix construction macros.

src/base/construction.rs

@@ -22,11 +22,12 @@ use crate::base::dimension::{Dim, DimName, Dynamic, U1, U2, U3, U4, U5, U6};
 use crate::base::storage::Storage;
 use crate::base::{DefaultAllocator, Matrix, MatrixMN, MatrixN, Scalar, Unit, Vector, VectorN};
 
-/*
+/// # Generic constructors
- *
+/// This set of matrix and vector construction functions are all generic
- * Generic constructors.
+/// with-regard to the matrix dimensions. They all expect to be given
- *
+/// the dimension as inputs.
- */
+///
+/// These functions should only be used when working on dimension-generic code.
 impl<N: Scalar, R: Dim, C: Dim> MatrixMN<N, R, C>
 where
     DefaultAllocator: Allocator<N, R, C>,
@@ -350,9 +351,6 @@ where
  */
 macro_rules! impl_constructors(
     ($($Dims: ty),*; $(=> $DimIdent: ident: $DimBound: ident),*; $($gargs: expr),*; $($args: ident),*) => {
-        impl<N: Scalar, $($DimIdent: $DimBound, )*> MatrixMN<N $(, $Dims)*>
-            where DefaultAllocator: Allocator<N $(, $Dims)*> {
-
         /// Creates a new uninitialized matrix or vector.
         #[inline]
         pub unsafe fn new_uninitialized($($args: usize),*) -> Self {
@@ -577,48 +575,66 @@ macro_rules! impl_constructors(
         ) -> Self {
             Self::from_distribution_generic($($gargs, )* distribution, rng)
         }
-        }
-
-        impl<N: Scalar, $($DimIdent: $DimBound, )*> MatrixMN<N $(, $Dims)*>
-            where
-            DefaultAllocator: Allocator<N $(, $Dims)*>,
-            Standard: Distribution<N> {
 
         /// Creates a matrix filled with random values.
         #[inline]
         #[cfg(feature = "std")]
-            pub fn new_random($($args: usize),*) -> Self {
+        pub fn new_random($($args: usize),*) -> Self
+            where Standard: Distribution<N> {
             Self::new_random_generic($($gargs),*)
         }
     }
-    }
 );
 
-// FIXME: this is not very pretty. We could find a better call syntax.
+/// # Constructors of statically-sized vectors or statically-sized matrices
-impl_constructors!(R, C;                         // Arguments for Matrix<N, ..., S>
+impl<N: Scalar, R: DimName, C: DimName> MatrixMN<N, R, C>
-=> R: DimName, => C: DimName; // Type parameters for impl<N, ..., S>
+where
-R::name(), C::name();         // Arguments for `_generic` constructors.
+    DefaultAllocator: Allocator<N, R, C>,
-); // Arguments for non-generic constructors.
+{
+    // FIXME: this is not very pretty. We could find a better call syntax.
+    impl_constructors!(R, C;                         // Arguments for Matrix<N, ..., S>
+    => R: DimName, => C: DimName; // Type parameters for impl<N, ..., S>
+    R::name(), C::name();         // Arguments for `_generic` constructors.
+    ); // Arguments for non-generic constructors.
+}
 
-impl_constructors!(R, Dynamic;
+/// # Constructors of matrices with a dynamic number of columns
+impl<N: Scalar, R: DimName> MatrixMN<N, R, Dynamic>
+where
+    DefaultAllocator: Allocator<N, R, Dynamic>,
+{
+    impl_constructors!(R, Dynamic;
                    => R: DimName;
                    R::name(), Dynamic::new(ncols);
                    ncols);
+}
 
-impl_constructors!(Dynamic, C;
+/// # Constructors of dynamic vectors and matrices with a dynamic number of rows
+impl<N: Scalar, C: DimName> MatrixMN<N, Dynamic, C>
+where
+    DefaultAllocator: Allocator<N, Dynamic, C>,
+{
+    impl_constructors!(Dynamic, C;
                    => C: DimName;
                    Dynamic::new(nrows), C::name();
                    nrows);
+}
 
-impl_constructors!(Dynamic, Dynamic;
+/// # Constructors of fully dynamic matrices
+impl<N: Scalar> MatrixMN<N, Dynamic, Dynamic>
+where
+    DefaultAllocator: Allocator<N, Dynamic, Dynamic>,
+{
+    impl_constructors!(Dynamic, Dynamic;
                    ;
                    Dynamic::new(nrows), Dynamic::new(ncols);
                    nrows, ncols);
+}
 
 /*
  *
  * Constructors that don't necessarily require all dimensions
- * to be specified whon one dimension is already known.
+ * to be specified when one dimension is already known.
  *
  */
 macro_rules! impl_constructors_from_data(

src/base/matrix.rs

@@ -54,7 +54,34 @@ pub type MatrixCross<N, R1, C1, R2, C2> =
 
 /// The most generic column-major matrix (and vector) type.
 ///
-/// It combines four type parameters:
+/// # Methods summary
+/// Because `Matrix` is the most generic types that groups all matrix and vectors of **nalgebra**
+/// this documentation page contains every single matrix/vector-related method. In order to make
+/// browsing this page simpler, the next subsections contain direct links to groups of methods
+/// related to a specific topic.
+///
+/// #### Vector and matrix construction
+/// - [Constructors of statically-sized vectors or statically-sized matrices](#constructors-of-statically-sized-vectors-or-statically-sized-matrices)
+///   (`Vector3`, `Matrix3x6`, etc.)
+/// - [Constructors of fully dynamic matrices](#constructors-of-fully-dynamic-matrices) (`DMatrix`)
+/// - [Constructors of dynamic vectors and matrices with a dynamic number of rows](#constructors-of-dynamic-vectors-and-matrices-with-a-dynamic-number-of-rows)
+///   (`DVector`, `MatrixXx3`, etc.)
+/// - [Constructors of matrices with a dynamic number of columns](#constructors-of-matrices-with-a-dynamic-number-of-columns)
+///   (`Matrix2xX`, etc.)
+/// - [Generic constructors](#generic-constructors)
+///   (For code generic wrt. the vectors or matrices dimensions.)
+/// #### Matrix decomposition
+/// - [Rectangular matrix decomposition](#rectangular-matrix-decomposition) (Applicable to square matrices too)
+/// - [Square matrix decomposition](#square-matrix-decomposition)
+///
+/// #### Vector and matrix slicing
+/// - [Slicing based on index and length](#slicing-based-on-index-and-length)
+/// - [Mutable slicing based on index and length](#mutable-slicing-based-on-index-and-length)
+/// - [Slicing based on ranges](#slicing-based-on-ranges)
+/// - [Mutable slicing based on ranges](#mutable-slicing-based-on-ranges)
+///
+/// # Type parameters
+/// The generic `Matrix` type has four type parameters:
 /// - `N`: for the matrix components scalar type.
 /// - `R`: for the matrix number of rows.
 /// - `C`: for the matrix number of columns.
@@ -75,26 +102,30 @@ pub type MatrixCross<N, R1, C1, R2, C2> =
 /// Note that mixing `Dynamic` with type-level unsigned integers is allowed. Actually, a
 /// dynamically-sized column vector should be represented as a `Matrix<N, Dynamic, U1, S>` (given
 /// some concrete types for `N` and a compatible data storage type `S`).
-///
-/// # Documentation by feature
-/// Because `Matrix` is the most generic types that groups all matrix and vectors of **nalgebra**
-/// this documentation page contains every single matrix/vector-related method. In order to make
-/// browsing this page simpler, the next subsections contain direct links to groups of methods
-/// related to a specific topic.
-///
-/// #### Matrix decomposition
-/// - [Rectangular matrix decomposition](#rectangular-matrix-decomposition).
-/// - [Square matrix decomposition](#square-matrix-decomposition).
-///
-/// #### Matrix slicing
-/// - [Slicing](#slicing)
-/// - [Mutable slicing](#mutable-slicing)
-/// - [Range-based slicing](#range-based-slicing), [mutable range-based slicing](#mutable-range-based-slicing).
 #[repr(C)]
 #[derive(Clone, Copy)]
 pub struct Matrix<N: Scalar, R: Dim, C: Dim, S> {
-    /// The data storage that contains all the matrix components and informations about its number
+    /// The data storage that contains all the matrix components. Disappointed?
-    /// of rows and column (if needed).
+    ///
+    /// Well, if you came here to see how you can access the matrix components,
+    /// you may be in luck: you can access the individual components of all vectors with compile-time
+    /// dimensions <= 6 using field notation like this:
+    /// `vec.x`, `vec.y`, `vec.z`, `vec.w`, `vec.a`, `vec.b`. Reference and assignation work too:
+    /// ```.ignore
+    /// let mut v = Vector3::new(1.0, 2.0, 3.0);
+    /// vec.x = 10.0;
+    /// my_function(&vec.z);
+    /// println!("{}", vec.y + 30.0);
+    /// ```
+    /// Similarly, for matrices with compile-time dimensions <= 6, you can use field notation
+    /// like this: `mat.m11`, `mat.m42`, etc. The first digit identifies the row to address
+    /// and the second digit identifies the column to address. So `mat.m13` identifies the component
+    /// at the first row and third column (note that the count of rows and columns start at 1 instead
+    /// of 0 here. This is so we match the mathematical notation).
+    ///
+    /// For all matrices and vectors, independently from their size, individual components can
+    /// be accessed and modified using indexing: `vec[20]`, `mat[(20, 19)]`. Here the indexing
+    /// starts at 0 as you would expect.
     pub data: S,
 
     _phantoms: PhantomData<(N, R, C)>,