Math: document some potentially non-obvious tricks.

src/Magnum/Math/Matrix3.h

@@ -87,7 +87,10 @@ template<class T> class Matrix3: public Matrix3x3<T> {
          * @brief 2D reflection matrix
          * @param normal    Normal of the line through which to reflect
          *
-         * Expects that the normal is normalized.
+         * Expects that the normal is normalized. Reflection along axes can be
+         * done in a slightly simpler way also using @ref scaling(), e.g.
+         * `Matrix3::reflection(Vector2::yAxis())` is equivalent to
+         * `Matrix3::scaling(Vector2::yScale(-1.0f))`.
          * @see @ref Matrix4::reflection(), @ref Vector::isNormalized()
          */
         static Matrix3<T> reflection(const Vector2<T>& normal) {

src/Magnum/Math/Matrix4.h

@@ -134,7 +134,10 @@ template<class T> class Matrix4: public Matrix4x4<T> {
          * @brief 3D reflection matrix
          * @param normal    Normal of the plane through which to reflect
          *
-         * Expects that the normal is normalized.
+         * Expects that the normal is normalized. Reflection along axes can be
+         * done in a slightly simpler way also using @ref scaling(), e.g.
+         * `Matrix4::reflection(Vector3::yAxis())` is equivalent to
+         * `Matrix4::scaling(Vector3::yScale(-1.0f))`.
          * @see @ref Matrix3::reflection(), @ref Vector::isNormalized()
          */
         static Matrix4<T> reflection(const Vector3<T>& normal);

src/Magnum/Math/Test/Matrix3Test.cpp

@@ -74,6 +74,7 @@ class Matrix3Test: public Corrade::TestSuite::Tester {
         void scaling();
         void rotation();
         void reflection();
+        void reflectionIsScaling();
         void projection();
         void fromParts();
         void rotationScalingPart();
@@ -110,6 +111,7 @@ Matrix3Test::Matrix3Test() {
               &Matrix3Test::scaling,
               &Matrix3Test::rotation,
               &Matrix3Test::reflection,
+              &Matrix3Test::reflectionIsScaling,
               &Matrix3Test::projection,
               &Matrix3Test::fromParts,
               &Matrix3Test::rotationScalingPart,
@@ -254,6 +256,10 @@ void Matrix3Test::reflection() {
     CORRADE_COMPARE(actual, expected);
 }
 
+void Matrix3Test::reflectionIsScaling() {
+    CORRADE_COMPARE(Matrix3::reflection(Vector2::yAxis()), Matrix3::scaling(Vector2::yScale(-1.0f)));
+}
+
 void Matrix3Test::projection() {
     Matrix3 expected({2.0f/4.0f,      0.0f, 0.0f},
                      {     0.0f, 2.0f/3.0f, 0.0f},

src/Magnum/Math/Test/Matrix4Test.cpp

@@ -79,6 +79,7 @@ class Matrix4Test: public Corrade::TestSuite::Tester {
         void rotationY();
         void rotationZ();
         void reflection();
+        void reflectionIsScaling();
         void orthographicProjection();
         void perspectiveProjection();
         void perspectiveProjectionFov();
@@ -120,6 +121,7 @@ Matrix4Test::Matrix4Test() {
               &Matrix4Test::rotationY,
               &Matrix4Test::rotationZ,
               &Matrix4Test::reflection,
+              &Matrix4Test::reflectionIsScaling,
               &Matrix4Test::orthographicProjection,
               &Matrix4Test::perspectiveProjection,
               &Matrix4Test::perspectiveProjectionFov,
@@ -317,6 +319,10 @@ void Matrix4Test::reflection() {
     CORRADE_COMPARE(actual, expected);
 }
 
+void Matrix4Test::reflectionIsScaling() {
+    CORRADE_COMPARE(Matrix4::reflection(Vector3::yAxis()), Matrix4::scaling(Vector3::yScale(-1.0f)));
+}
+
 void Matrix4Test::orthographicProjection() {
     Matrix4 expected({0.4f, 0.0f,   0.0f, 0.0f},
                      {0.0f, 0.5f,   0.0f, 0.0f},