From 9f7512bf2b07170f7a89615a828ac04668cc36d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 12 Oct 2018 17:06:16 +0200
Subject: [PATCH] Math: improve Constants docs, show useful identities.

---
 doc/changelog.dox           |  2 ++
 src/Magnum/Math/Constants.h | 47 +++++++++++++++++++++++++++++++------
 2 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/doc/changelog.dox b/doc/changelog.dox
index 1036b8bea..734563366 100644
--- a/doc/changelog.dox
+++ b/doc/changelog.dox
@@ -411,6 +411,8 @@ See also:
     and caveats
 -   Reworked documentation of @ref Math::Algorithms, adding math equations and
     usage examples to all functions
+-   Improved documentation of @ref Math::Constants, showing useful identities
+    for each
 -   Explicitly mentioning copy/move constructibility for all classes with
     non-trivial construction
 -   Improved Vcpkg build instructions (see
diff --git a/src/Magnum/Math/Constants.h b/src/Magnum/Math/Constants.h
index 60977adc6..9d1dbd940 100644
--- a/src/Magnum/Math/Constants.h
+++ b/src/Magnum/Math/Constants.h
@@ -46,30 +46,43 @@ template<class T> struct Constants {
     /* See TypeTraits for answer why these are functions and not constants. */
     #ifdef DOXYGEN_GENERATING_OUTPUT
     /**
-     * @brief Pi
+     * @brief @f$ \pi @f$.
      *
+     * @f[
+     *      \pi = 180 \degree
+     * @f]
      * @see @ref piHalf(), @ref piQuarter(), @ref tau(), @ref Deg, @ref Rad
      */
     static constexpr T pi();
 
     /**
-     * @brief Half of a pi
+     * @brief Half of a @f$ \pi @f$
      *
+     * @f[
+     *      \frac{\pi}{2} = 90 \degree
+     * @f]
      * @see @ref pi(), @ref piQuarter(), @ref tau(), @ref Deg, @ref Rad
      */
     static constexpr T piHalf();
 
     /**
-     * @brief Quarter of a pi
+     * @brief Quarter of a @f$ \pi @f$
      *
+     * @f[
+     *      \frac{\pi}{4} = 45 \degree
+     * @f]
      * @see @ref pi(), @ref piHalf(), @ref tau(), @ref Deg, @ref Rad
      */
     static constexpr T piQuarter();
 
     /**
-     * @brief Tau
+     * @brief @f$ \tau @f$.
      *
      * Or two pi. See the [Tau manifesto](https://www.tauday.com/tau-manifesto).
+     *
+     * @f[
+     *      \tau = 2 \pi = 360 \degree
+     * @f]
      * @see @ref pi(), @ref piHalf(), @ref piQuarter(), @ref Deg, @ref Rad
      */
     static constexpr T tau();
@@ -77,12 +90,32 @@ template<class T> struct Constants {
     /**
      * @brief Euler's number
      *
+     * @f[
+     *      e = \ln (1)
+     * @f]
      * @see @ref log(), @ref exp()
      */
     static constexpr T e();
 
-    static constexpr T sqrt2(); /**< @brief Square root of 2 */
-    static constexpr T sqrt3(); /**< @brief Square root of 3 */
+    /**
+     * @brief Square root of 2
+     *
+     * @f[
+     *      \sqrt{2}
+     * @f]
+     * @see @ref sqrt3(), @ref sqrtHalf()
+     */
+    static constexpr T sqrt2();
+
+    /**
+     * @brief Square root of 3
+     *
+     * @f[
+     *      \sqrt{3}
+     * @f]
+     * @see @ref sqrt2(), @ref sqrtHalf()
+     */
+    static constexpr T sqrt3();
 
     /**
      * @brief Quiet NaN
@@ -92,7 +125,7 @@ template<class T> struct Constants {
     static constexpr T nan();
 
     /**
-     * @brief Positive infinity
+     * @brief Positive @f$ \infty @f$.
      *
      * @see @ref isInf()
      */