From f68e277a4195c9e76f4c81fb2fdd7df7e8af1a84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Wed, 7 Jan 2026 22:21:38 +0100
Subject: [PATCH] Math: clearly document what the TypeForSize helper is for.

I was initially not sure if it has some other use than the swizzle APIs.
It doesn't, so mention that clearly.
---
 src/Magnum/Math/Color.h   | 1 +
 src/Magnum/Math/Swizzle.h | 3 +++
 src/Magnum/Math/Vector2.h | 1 +
 src/Magnum/Math/Vector3.h | 1 +
 src/Magnum/Math/Vector4.h | 1 +
 5 files changed, 7 insertions(+)

diff --git a/src/Magnum/Math/Color.h b/src/Magnum/Math/Color.h
index 376fa068e..a544e35a8 100644
--- a/src/Magnum/Math/Color.h
+++ b/src/Magnum/Math/Color.h
@@ -1942,6 +1942,7 @@ MAGNUM_EXPORT Debug& operator<<(Debug& debug, const Color4<UnsignedByte>& value)
 #endif
 
 namespace Implementation {
+    /* Used by Swizzle.h */
     template<class T> struct TypeForSize<3, Color3<T>> { typedef Color3<T> Type; };
     template<class T> struct TypeForSize<3, Color4<T>> { typedef Color3<T> Type; };
     template<class T> struct TypeForSize<4, Color3<T>> { typedef Color4<T> Type; };
diff --git a/src/Magnum/Math/Swizzle.h b/src/Magnum/Math/Swizzle.h
index a031c434c..beacf3ad4 100644
--- a/src/Magnum/Math/Swizzle.h
+++ b/src/Magnum/Math/Swizzle.h
@@ -59,6 +59,9 @@ namespace Implementation {
         template<class T> constexpr static T value(const Math::Vector<size, T>&) { return T(1); }
     };
 
+    /* Additional specializations in Vector2.h, Vector3.h, Vector4.h and
+       Color.h. That way it's possible to return a concrete Vector subtype
+       without having to include it directly from here. */
     template<std::size_t size, class T> struct TypeForSize {
         typedef Math::Vector<size, typename T::Type> Type;
     };
diff --git a/src/Magnum/Math/Vector2.h b/src/Magnum/Math/Vector2.h
index 66b064323..0d56d17b2 100644
--- a/src/Magnum/Math/Vector2.h
+++ b/src/Magnum/Math/Vector2.h
@@ -250,6 +250,7 @@ _MAGNUM_VECTORn_OPERATOR_IMPLEMENTATION(2, Vector2)
 #endif
 
 namespace Implementation {
+    /* Used by Swizzle.h */
     template<std::size_t, class> struct TypeForSize;
     template<class T> struct TypeForSize<2, T> { typedef Math::Vector2<typename T::Type> Type; };
     #ifndef MAGNUM_NO_MATH_STRICT_WEAK_ORDERING
diff --git a/src/Magnum/Math/Vector3.h b/src/Magnum/Math/Vector3.h
index 0d720d23d..9904ac9e8 100644
--- a/src/Magnum/Math/Vector3.h
+++ b/src/Magnum/Math/Vector3.h
@@ -288,6 +288,7 @@ _MAGNUM_VECTORn_OPERATOR_IMPLEMENTATION(3, Vector3)
 #endif
 
 namespace Implementation {
+    /* Used by Swizzle.h */
     template<class T> struct TypeForSize<3, T> { typedef Math::Vector3<typename T::Type> Type; };
     #ifndef MAGNUM_NO_MATH_STRICT_WEAK_ORDERING
     template<class T> struct StrictWeakOrdering<Vector3<T>>: StrictWeakOrdering<Vector<3, T>> {};
diff --git a/src/Magnum/Math/Vector4.h b/src/Magnum/Math/Vector4.h
index 0fe1ee322..93a6d353d 100644
--- a/src/Magnum/Math/Vector4.h
+++ b/src/Magnum/Math/Vector4.h
@@ -315,6 +315,7 @@ template<class T> Vector4<T> planeEquation(const Vector3<T>& normal, const Vecto
 }
 
 namespace Implementation {
+    /* Used by Swizzle.h */
     template<class T> struct TypeForSize<4, T> { typedef Math::Vector4<typename T::Type> Type; };
     #ifndef MAGNUM_NO_MATH_STRICT_WEAK_ORDERING
     template<class T> struct StrictWeakOrdering<Vector4<T>>: StrictWeakOrdering<Vector<4, T>> {};