Add doc-tests for componentwise operations.

src/base/componentwise.rs

@@ -11,11 +11,20 @@ use base::dimension::Dim;
 use base::storage::{Storage, StorageMut};
 use base::{DefaultAllocator, Matrix, MatrixMN, MatrixSum, Scalar};
 
-/// The type of the result of a matrix componentwise operation.
+/// The type of the result of a matrix component-wise operation.
 pub type MatrixComponentOp<N, R1, C1, R2, C2> = MatrixSum<N, R1, C1, R2, C2>;
 
 impl<N: Scalar, R: Dim, C: Dim, S: Storage<N, R, C>> Matrix<N, R, C, S> {
-    /// Computes the componentwise absolute value.
+    /// Computes the component-wise absolute value.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use nalgebra::Matrix2;
+    /// let a = Matrix2::new(0.0, 1.0,
+    ///                      -2.0, -3.0);
+    /// assert_eq!(a.abs(), Matrix2::new(0.0, 1.0, 2.0, 3.0))
+    /// ```
     #[inline]
     pub fn abs(&self) -> MatrixMN<N, R, C>
     where
@@ -135,12 +144,94 @@ macro_rules! component_binop_impl(
 
 component_binop_impl!(
     component_mul, component_mul_mut, component_mul_assign, cmpy, ClosedMul.mul.mul_assign,
-    "Componentwise matrix multiplication.",
-    "Computes componentwise `self[i] = alpha * a[i] * b[i] + beta * self[i]`.",
-    "Inplace componentwise matrix multiplication.";
+    r"
+    Componentwise matrix or vector multiplication.
+
+    # Example
+
+    ```
+    # use nalgebra::Matrix2;
+    let a = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = Matrix2::new(0.0, 5.0, 12.0, 21.0);
+
+    assert_eq!(a.component_mul(&b), expected);
+    ```
+    ",
+    r"
+    Computes componentwise `self[i] = alpha * a[i] * b[i] + beta * self[i]`.
+
+    # Example
+    ```
+    # use nalgebra::Matrix2;
+    let mut m = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let a = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = (a.component_mul(&b) * 5.0) + m * 10.0;
+
+    m.cmpy(5.0, &a, &b, 10.0);
+    assert_eq!(m, expected);
+    ```
+    ",
+    r"
+    Inplace componentwise matrix or vector multiplication.
+
+    # Example
+    ```
+    # use nalgebra::Matrix2;
+    let mut a = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = Matrix2::new(0.0, 5.0, 12.0, 21.0);
+
+    a.component_mul_assign(&b);
+
+    assert_eq!(a, expected);
+    ```
+    ";
     component_div, component_div_mut, component_div_assign, cdpy, ClosedDiv.div.div_assign,
-    "Componentwise matrix division.",
-    "Computes componentwise `self[i] = alpha * a[i] / b[i] + beta * self[i]`.",    
-    "Inplace componentwise matrix division.";
+    r"
+    Componentwise matrix or vector division.
+
+    # Example
+
+    ```
+    # use nalgebra::Matrix2;
+    let a = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = Matrix2::new(0.0, 1.0 / 5.0, 2.0 / 6.0, 3.0 / 7.0);
+
+    assert_eq!(a.component_div(&b), expected);
+    ```
+    ",
+    r"
+    Computes componentwise `self[i] = alpha * a[i] / b[i] + beta * self[i]`.
+
+    # Example
+    ```
+    # use nalgebra::Matrix2;
+    let mut m = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let a = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = (a.component_div(&b) * 5.0) + m * 10.0;
+
+    m.cdpy(5.0, &a, &b, 10.0);
+    assert_eq!(m, expected);
+    ```
+    ",
+    r"
+    Inplace componentwise matrix or vector division.
+
+    # Example
+    ```
+    # use nalgebra::Matrix2;
+    let mut a = Matrix2::new(0.0, 1.0, 2.0, 3.0);
+    let b = Matrix2::new(4.0, 5.0, 6.0, 7.0);
+    let expected = Matrix2::new(0.0, 1.0 / 5.0, 2.0 / 6.0, 3.0 / 7.0);
+
+    a.component_div_assign(&b);
+
+    assert_eq!(a, expected);
+    ```
+    ";
     // FIXME: add other operators like bitshift, etc. ?
 );