From 9bd2890875ac5d096c7159a9d87577c87a35c2bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= Date: Fri, 2 Feb 2018 12:26:40 +0100 Subject: [PATCH] Add documentation. --- src/core/componentwise.rs | 13 ++++++--- src/core/construction_slice.rs | 50 +++++++++++++++++++++++++++++++++- src/lib.rs | 2 +- 3 files changed, 59 insertions(+), 6 deletions(-) diff --git a/src/core/componentwise.rs b/src/core/componentwise.rs index 26d7051f..979de438 100644 --- a/src/core/componentwise.rs +++ b/src/core/componentwise.rs @@ -35,7 +35,7 @@ impl> Matrix { } macro_rules! component_binop_impl( - ($($binop: ident, $binop_mut: ident, $binop_assign: ident, $cbpy: ident, $Trait: ident . $op: ident . $op_assign: ident, $desc:expr, $desc_mut:expr);* $(;)*) => {$( + ($($binop: ident, $binop_mut: ident, $binop_assign: ident, $cmpy: ident, $Trait: ident . $op: ident . $op_assign: ident, $desc:expr, $desc_cmpy:expr, $desc_mut:expr);* $(;)*) => {$( impl> Matrix { #[doc = $desc] #[inline] @@ -63,8 +63,9 @@ macro_rules! component_binop_impl( impl> Matrix { // componentwise binop plus Y. + #[doc = $desc_cmpy] #[inline] - pub fn $cbpy(&mut self, alpha: N, a: &Matrix, b: &Matrix, beta: N) + pub fn $cmpy(&mut self, alpha: N, a: &Matrix, b: &Matrix, beta: N) where N: $Trait + Zero + Mul + Add, R2: Dim, C2: Dim, R3: Dim, C3: Dim, @@ -134,8 +135,12 @@ macro_rules! component_binop_impl( component_binop_impl!( component_mul, component_mul_mut, component_mul_assign, cmpy, ClosedMul.mul.mul_assign, - "Componentwise matrix multiplication.", "Mutable, componentwise matrix multiplication."; + "Componentwise matrix multiplication.", + "Computes componentwise `self[i] = alpha * a[i] * b[i] + beta * self[i]", + "Inplace componentwise matrix multiplication."; component_div, component_div_mut, component_div_assign, cdpy, ClosedDiv.div.div_assign, - "Componentwise matrix division.", "Mutable, componentwise matrix division."; + "Componentwise matrix division.", + "Computes componentwise `self[i] = alpha * a[i] / b[i] + beta * self[i]", + "Inplace componentwise matrix division."; // FIXME: add other operators like bitshift, etc. ? ); diff --git a/src/core/construction_slice.rs b/src/core/construction_slice.rs index 9ff1c581..174d95fb 100644 --- a/src/core/construction_slice.rs +++ b/src/core/construction_slice.rs @@ -9,6 +9,10 @@ use core::matrix_slice::{SliceStorage, SliceStorageMut}; */ impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> MatrixSliceMN<'a, N, R, C, RStride, CStride> { + /// Creates, without bound-checking, a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// This method is unsafe because the input data array is not checked to contain enough elements. + /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub unsafe fn new_with_strides_generic_unchecked( data: &'a [N], @@ -26,6 +30,10 @@ impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> Self::from_data(data) } + /// Creates a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// Panics if the input data array dose not contain enough elements. + /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub fn new_with_strides_generic( data: &'a [N], @@ -49,6 +57,11 @@ impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> MatrixSliceMutMN<'a, N, R, C, RStride, CStride> { + + /// Creates, without bound-checking, a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// This method is unsafe because the input data array is not checked to contain enough elements. + /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub unsafe fn new_with_strides_generic_mut_unchecked( data: &'a mut [N], @@ -66,6 +79,10 @@ impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> Self::from_data(data) } + /// Creates a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// Panics if the input data array dose not contain enough elements. + /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub fn new_with_strides_generic_mut( data: &'a mut [N], @@ -90,11 +107,19 @@ impl<'a, N: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> } impl<'a, N: Scalar, R: Dim, C: Dim> MatrixSliceMN<'a, N, R, C> { + /// Creates, without bound-checking, a matrix slice from an array and with dimensions specified by generic types instances. + /// + /// This method is unsafe because the input data array is not checked to contain enough elements. + /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub unsafe fn new_generic_unchecked(data: &'a [N], start: usize, nrows: R, ncols: C) -> Self { Self::new_with_strides_generic_unchecked(data, start, nrows, ncols, U1, nrows) } + /// Creates a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// Panics if the input data array dose not contain enough elements. + /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub fn new_generic(data: &'a [N], nrows: R, ncols: C) -> Self { Self::new_with_strides_generic(data, nrows, ncols, U1, nrows) @@ -102,6 +127,10 @@ impl<'a, N: Scalar, R: Dim, C: Dim> MatrixSliceMN<'a, N, R, C> { } impl<'a, N: Scalar, R: Dim, C: Dim> MatrixSliceMutMN<'a, N, R, C> { + /// Creates, without bound-checking, a mutable matrix slice from an array and with dimensions specified by generic types instances. + /// + /// This method is unsafe because the input data array is not checked to contain enough elements. + /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub unsafe fn new_generic_mut_unchecked( data: &'a mut [N], @@ -112,6 +141,10 @@ impl<'a, N: Scalar, R: Dim, C: Dim> MatrixSliceMutMN<'a, N, R, C> { Self::new_with_strides_generic_mut_unchecked(data, start, nrows, ncols, U1, nrows) } + /// Creates a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// + /// Panics if the input data array dose not contain enough elements. + /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. #[inline] pub fn new_generic_mut(data: &'a mut [N], nrows: R, ncols: C) -> Self { Self::new_with_strides_generic_mut(data, nrows, ncols, U1, nrows) @@ -121,11 +154,15 @@ impl<'a, N: Scalar, R: Dim, C: Dim> MatrixSliceMutMN<'a, N, R, C> { macro_rules! impl_constructors( ($($Dims: ty),*; $(=> $DimIdent: ident: $DimBound: ident),*; $($gargs: expr),*; $($args: ident),*) => { impl<'a, N: Scalar, $($DimIdent: $DimBound),*> MatrixSliceMN<'a, N, $($Dims),*> { + /// Creates a new matrix slice from the given data array. + /// + /// Panics if `data` does not contain enough elements. #[inline] pub fn new(data: &'a [N], $($args: usize),*) -> Self { Self::new_generic(data, $($gargs),*) } + /// Creates, without bound checking, a new matrix slice from the given data array. #[inline] pub unsafe fn new_unchecked(data: &'a [N], start: usize, $($args: usize),*) -> Self { Self::new_generic_unchecked(data, start, $($gargs),*) @@ -133,11 +170,15 @@ macro_rules! impl_constructors( } impl<'a, N: Scalar, $($DimIdent: $DimBound, )*> MatrixSliceMN<'a, N, $($Dims,)* Dynamic, Dynamic> { + /// Creates a new matrix slice with the specified strides from the given data array. + /// + /// Panics if `data` does not contain enough elements. #[inline] pub fn new_with_strides(data: &'a [N], $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::new_with_strides_generic(data, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) } + /// Creates, without bound checking, a new matrix slice with the specified strides from the given data array. #[inline] pub unsafe fn new_with_strides_unchecked(data: &'a [N], start: usize, $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::new_with_strides_generic_unchecked(data, start, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) @@ -170,12 +211,15 @@ impl_constructors!(Dynamic, Dynamic; macro_rules! impl_constructors_mut( ($($Dims: ty),*; $(=> $DimIdent: ident: $DimBound: ident),*; $($gargs: expr),*; $($args: ident),*) => { impl<'a, N: Scalar, $($DimIdent: $DimBound),*> MatrixSliceMutMN<'a, N, $($Dims),*> { - + /// Creates a new mutable matrix slice from the given data array. + /// + /// Panics if `data` does not contain enough elements. #[inline] pub fn new(data: &'a mut [N], $($args: usize),*) -> Self { Self::new_generic_mut(data, $($gargs),*) } + /// Creates, without bound checking, a new mutable matrix slice from the given data array. #[inline] pub unsafe fn new_unchecked(data: &'a mut [N], start: usize, $($args: usize),*) -> Self { Self::new_generic_mut_unchecked(data, start, $($gargs),*) @@ -183,12 +227,16 @@ macro_rules! impl_constructors_mut( } impl<'a, N: Scalar, $($DimIdent: $DimBound, )*> MatrixSliceMutMN<'a, N, $($Dims,)* Dynamic, Dynamic> { + /// Creates a new mutable matrix slice with the specified strides from the given data array. + /// + /// Panics if `data` does not contain enough elements. #[inline] pub fn new_with_strides(data: &'a mut [N], $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::new_with_strides_generic_mut( data, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) } + /// Creates, without bound checking, a new mutable matrix slice with the specified strides from the given data array. #[inline] pub unsafe fn new_with_strides_unchecked(data: &'a mut [N], start: usize, $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::new_with_strides_generic_mut_unchecked( diff --git a/src/lib.rs b/src/lib.rs index 6ecd2e2f..e67e31b3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -81,7 +81,7 @@ an optimized set of tools for computer graphics and physics. Those features incl #![deny(non_upper_case_globals)] #![deny(unused_qualifications)] #![deny(unused_results)] -// #![warn(missing_docs)] +#![deny(missing_docs)] #![doc(html_root_url = "http://nalgebra.org/rustdoc")] #[cfg(feature = "arbitrary")]