From 2c27831b0a638a8964305f6f9d78c128414d8d52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Tue, 18 Apr 2023 09:32:24 +0200
Subject: [PATCH] MeshTools,Trade: clarify why offset-only attributes can't be
 used.

Instead of saying "which is not supported" in each assert, which is
vague and might imply that "it eventually will be supported", document
the actual reason in a single place, which is the MeshAttributeData docs.
---
 src/Magnum/MeshTools/Combine.cpp             | 2 +-
 src/Magnum/MeshTools/Duplicate.cpp           | 2 +-
 src/Magnum/MeshTools/Interleave.cpp          | 2 +-
 src/Magnum/MeshTools/Test/CombineTest.cpp    | 2 +-
 src/Magnum/MeshTools/Test/DuplicateTest.cpp  | 2 +-
 src/Magnum/MeshTools/Test/InterleaveTest.cpp | 2 +-
 src/Magnum/Trade/MeshData.h                  | 8 +++++---
 7 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/Magnum/MeshTools/Combine.cpp b/src/Magnum/MeshTools/Combine.cpp
index a598d32fb..e8373aa3c 100644
--- a/src/Magnum/MeshTools/Combine.cpp
+++ b/src/Magnum/MeshTools/Combine.cpp
@@ -239,7 +239,7 @@ Trade::MeshData combineFaceAttributes(const Trade::MeshData& mesh, Containers::A
     #ifndef CORRADE_NO_ASSERT
     for(std::size_t i = 0; i != faceAttributes.size(); ++i)
         CORRADE_ASSERT(!faceAttributes[i].isOffsetOnly(),
-            "MeshTools::combineFaceAttributes(): face attribute" << i << "is offset-only, which is not supported",
+            "MeshTools::combineFaceAttributes(): face attribute" << i << "is offset-only",
                 (Trade::MeshData{MeshPrimitive::Triangles, 0}));
     #endif
 
diff --git a/src/Magnum/MeshTools/Duplicate.cpp b/src/Magnum/MeshTools/Duplicate.cpp
index 209019862..4b985b285 100644
--- a/src/Magnum/MeshTools/Duplicate.cpp
+++ b/src/Magnum/MeshTools/Duplicate.cpp
@@ -116,7 +116,7 @@ Trade::MeshData duplicate(const Trade::MeshData& mesh, const Containers::ArrayVi
         /* Asserting here even though data() has another assert since that one
            would be too confusing in this context */
         CORRADE_ASSERT(!extra[i].isOffsetOnly(),
-            "MeshTools::duplicate(): extra attribute" << i << "is offset-only, which is not supported",
+            "MeshTools::duplicate(): extra attribute" << i << "is offset-only",
             (Trade::MeshData{MeshPrimitive::Triangles, 0}));
 
         /* Copy the attribute in, if it is non-empty, otherwise keep the
diff --git a/src/Magnum/MeshTools/Interleave.cpp b/src/Magnum/MeshTools/Interleave.cpp
index 173c5ccc1..5ba11b8ba 100644
--- a/src/Magnum/MeshTools/Interleave.cpp
+++ b/src/Magnum/MeshTools/Interleave.cpp
@@ -346,7 +346,7 @@ Trade::MeshData interleave(Trade::MeshData&& mesh, const Containers::ArrayView<c
             /* Asserting here even though data() has another assert since that
                one would be too confusing in this context */
             CORRADE_ASSERT(!extra[i].isOffsetOnly(),
-                "MeshTools::interleave(): extra attribute" << i << "is offset-only, which is not supported",
+                "MeshTools::interleave(): extra attribute" << i << "is offset-only",
                 (Trade::MeshData{MeshPrimitive::Triangles, 0}));
 
             /* Copy the attribute in, if it is non-empty, otherwise keep the
diff --git a/src/Magnum/MeshTools/Test/CombineTest.cpp b/src/Magnum/MeshTools/Test/CombineTest.cpp
index cda4d9485..69f402abf 100644
--- a/src/Magnum/MeshTools/Test/CombineTest.cpp
+++ b/src/Magnum/MeshTools/Test/CombineTest.cpp
@@ -571,7 +571,7 @@ void CombineTest::combineFaceAttributesFaceAttributeOffsetOnly() {
             VertexFormat::Vector4, 0, 5, 16}
     });
     CORRADE_COMPARE(out.str(),
-        "MeshTools::combineFaceAttributes(): face attribute 1 is offset-only, which is not supported\n");
+        "MeshTools::combineFaceAttributes(): face attribute 1 is offset-only\n");
 }
 
 }}}}
diff --git a/src/Magnum/MeshTools/Test/DuplicateTest.cpp b/src/Magnum/MeshTools/Test/DuplicateTest.cpp
index 3f60fb4d9..310d263d1 100644
--- a/src/Magnum/MeshTools/Test/DuplicateTest.cpp
+++ b/src/Magnum/MeshTools/Test/DuplicateTest.cpp
@@ -457,7 +457,7 @@ void DuplicateTest::duplicateMeshDataExtraOffsetOnly() {
         Trade::MeshAttributeData{10},
         Trade::MeshAttributeData{Trade::MeshAttribute::Normal, VertexFormat::Vector3, 3, 5, 14}
     });
-    CORRADE_COMPARE(out.str(), "MeshTools::duplicate(): extra attribute 1 is offset-only, which is not supported\n");
+    CORRADE_COMPARE(out.str(), "MeshTools::duplicate(): extra attribute 1 is offset-only\n");
 }
 
 void DuplicateTest::duplicateMeshDataExtraImplementationSpecificVertexFormat() {
diff --git a/src/Magnum/MeshTools/Test/InterleaveTest.cpp b/src/Magnum/MeshTools/Test/InterleaveTest.cpp
index da19bd1f9..668122cb5 100644
--- a/src/Magnum/MeshTools/Test/InterleaveTest.cpp
+++ b/src/Magnum/MeshTools/Test/InterleaveTest.cpp
@@ -1350,7 +1350,7 @@ void InterleaveTest::interleaveMeshDataExtraOffsetOnly() {
         Trade::MeshAttributeData{10},
         Trade::MeshAttributeData{Trade::MeshAttribute::Normal, VertexFormat::Vector3, 3, 5, 14}
     });
-    CORRADE_COMPARE(out.str(), "MeshTools::interleave(): extra attribute 1 is offset-only, which is not supported\n");
+    CORRADE_COMPARE(out.str(), "MeshTools::interleave(): extra attribute 1 is offset-only\n");
 }
 
 void InterleaveTest::interleaveMeshDataExtraImplementationSpecificVertexFormat() {
diff --git a/src/Magnum/Trade/MeshData.h b/src/Magnum/Trade/MeshData.h
index 41fd1b944..6d035f2b4 100644
--- a/src/Magnum/Trade/MeshData.h
+++ b/src/Magnum/Trade/MeshData.h
@@ -414,9 +414,11 @@ but the actual data is allocated / populated at runtime:
 
 @snippet MagnumTrade.cpp MeshAttributeData-usage-offset-only
 
-Note that @ref MeshTools algorithms generally don't accept offset-only
-@ref MeshAttributeData instances except when passed through a @ref MeshData
-instance.
+Offset-only attributes return @cpp true @ce for @ref isOffsetOnly(). Note that
+@ref MeshTools algorithms generally don't accept offset-only
+@ref MeshAttributeData instances except when passed through a @ref MeshData, as
+for a standalone offset-only @ref MeshAttributeData it's impossible to know
+what data it points to.
 
 @section Trade-MeshAttributeData-custom-vertex-format Custom vertex formats