Math: better document Quaternion::axis() caveats.

doc/snippets/MagnumMath.cpp

@@ -1105,6 +1105,15 @@ Quaternion a =
 static_cast<void>(a);
 }
 
+{
+/* [Quaternion-axis-nan] */
+Quaternion a = DOXYGEN_ELLIPSIS({});
+Rad angle = a.angle();
+Vector3 axis = angle == 0.0_radf ? Vector3::xAxis() : a.axis();
+/* [Quaternion-axis-nan] */
+static_cast<void>(axis);
+}
+
 {
 /* [unpack-template-explicit] */
 // Literal type is (signed) char, but we assumed unsigned char, a != 1.0f

src/Magnum/Math/Quaternion.h

@@ -435,12 +435,20 @@ template<class T> class Quaternion {
         /**
          * @brief Rotation axis of a unit quaternion
          *
-         * Expects that the quaternion is normalized. Returns either unit-length
-         * vector for valid rotation quaternion or NaN vector for
-         * default-constructed quaternion. @f[
+         * Expects that the quaternion is normalized. @f[
          *      \boldsymbol a = \frac{\boldsymbol q_V}{\sqrt{1 - q_S^2}}
          * @f]
-         * @see @ref isNormalized(), @ref angle(), @ref rotation()
+         *
+         * If the @ref angle() is zero, the returned axis is a NaN vector,
+         * indicating that the axis is arbitrary. In other words, rotating
+         * by a zero angle around any axis will always give back a
+         * @f$ [\boldsymbol 0, 1] @f$ quaternion. To always get a unit vector
+         * back, you do the following, replace it with an X axis for a zero
+         * angle:
+         *
+         * @snippet MagnumMath.cpp Quaternion-axis-nan
+         *
+         * @see @ref isNormalized(), @ref rotation()
          */
         Vector3<T> axis() const;