From 755d97121cbc6d1edd420f0dd01091f676c6d255 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Tue, 16 Feb 2021 19:50:32 +0100
Subject: [PATCH] doc: discourage using MeshIndexType::UnsignedByte.

---
 src/Magnum/GL/Mesh.h | 15 ++++++++++++---
 src/Magnum/Mesh.h    | 13 +++++++------
 src/Magnum/Vk/Mesh.h |  9 ++++++++-
 3 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/src/Magnum/GL/Mesh.h b/src/Magnum/GL/Mesh.h
index a60395167..e236b523c 100644
--- a/src/Magnum/GL/Mesh.h
+++ b/src/Magnum/GL/Mesh.h
@@ -172,11 +172,20 @@ MAGNUM_GL_EXPORT MeshPrimitive meshPrimitive(Magnum::MeshPrimitive primitive);
 @m_enum_values_as_keywords
 */
 enum class MeshIndexType: GLenum {
-    UnsignedByte = GL_UNSIGNED_BYTE,    /**< Unsigned byte */
-    UnsignedShort = GL_UNSIGNED_SHORT,  /**< Unsigned short */
+    /**
+     * @relativeref{Magnum,UnsignedByte}.
+     *
+     * Even though OpenGL historically supports 8-bit indices, using this type
+     * is discouraged on contemporary GPU architectures. Prefer using 16-bit
+     * indices instead.
+     */
+    UnsignedByte = GL_UNSIGNED_BYTE,
+
+    /** @relativeref{Magnum,UnsignedShort} */
+    UnsignedShort = GL_UNSIGNED_SHORT,
 
     /**
-     * Unsigned int
+     * @relativeref{Magnum,UnsignedInt}
      * @requires_gles30 Extension @gl_extension{OES,element_index_uint}
      *       in OpenGL ES 2.0.
      * @requires_webgl20 Extension @webgl_extension{OES,element_index_uint}
diff --git a/src/Magnum/Mesh.h b/src/Magnum/Mesh.h
index 36b4b9351..5ef337e51 100644
--- a/src/Magnum/Mesh.h
+++ b/src/Magnum/Mesh.h
@@ -249,17 +249,18 @@ enum class MeshIndexType: UnsignedByte {
     /* Zero reserved for an invalid type (but not being a named value) */
 
     /**
-     * Unsigned byte
+     * @relativeref{Magnum,UnsignedByte}.
      *
      * Corresponds to @ref GL::MeshIndexType::UnsignedByte /
-     * @ref Vk::MeshIndexTyúe::UnsignedByte. Note that using this
-     * type is discouraged, at least AMD GPUs are known to suggest (via debug
-     * output) using 16-byte types instead for better efficiency.
+     * @ref Vk::MeshIndexType::UnsignedByte. Even though OpenGL supports this
+     * type and Vulkan can as well via an extension, using this type is
+     * discouraged on contemporary GPU architectures. Prefer using 16-bit
+     * indices instead.
      */
     UnsignedByte = 1,
 
     /**
-     * Unsigned short
+     * @relativeref{Magnum,UnsignedShort}.
      *
      * Corresponds to @ref GL::MeshIndexType::UnsignedShort /
      * @ref Vk::MeshIndexType::UnsignedShort.
@@ -267,7 +268,7 @@ enum class MeshIndexType: UnsignedByte {
     UnsignedShort,
 
     /**
-     * Unsigned int
+     * @relativeref{Magnum,UnsignedInt}.
      *
      * Corresponds to @ref GL::MeshIndexType::UnsignedInt /
      * @ref Vk::MeshIndexType::UnsignedInt.
diff --git a/src/Magnum/Vk/Mesh.h b/src/Magnum/Vk/Mesh.h
index c6a821ce4..2ce1a7829 100644
--- a/src/Magnum/Vk/Mesh.h
+++ b/src/Magnum/Vk/Mesh.h
@@ -44,7 +44,14 @@ Wraps a @type_vk_keyword{IndexType}.
 */
 enum class MeshIndexType: Int {
     /**
-     * @ref Magnum::UnsignedByte "UnsignedByte"
+     * @ref Magnum::UnsignedByte "UnsignedByte".
+     *
+     * @m_class{m-note m-success}
+     *
+     * @par
+     *      Discouraged on contemporary GPU architectures, prefer to use 16-bit
+     *      indices instead.
+     *
      * @requires_vk_feature @ref DeviceFeature::IndexTypeUnsignedByte
      */
     UnsignedByte = VK_INDEX_TYPE_UINT8_EXT,