From cb7dd224db8f9e4e4e874ae5f488dd9da9fd514c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 6 Jun 2022 19:05:44 +0200
Subject: [PATCH] Trade: doc++, minor.

---
 src/Magnum/Trade/FlatMaterialData.h           |  9 +++--
 src/Magnum/Trade/MaterialData.h               |  2 +-
 src/Magnum/Trade/PbrClearCoatMaterialData.h   | 21 +++++++----
 .../PbrMetallicRoughnessMaterialData.cpp      |  2 +-
 .../Trade/PbrMetallicRoughnessMaterialData.h  | 20 ++++++----
 .../Trade/PbrSpecularGlossinessMaterialData.h | 37 ++++++++++---------
 src/Magnum/Trade/PhongMaterialData.h          | 16 ++++----
 7 files changed, 62 insertions(+), 45 deletions(-)

diff --git a/src/Magnum/Trade/FlatMaterialData.h b/src/Magnum/Trade/FlatMaterialData.h
index 133ee2547..707d16d1a 100644
--- a/src/Magnum/Trade/FlatMaterialData.h
+++ b/src/Magnum/Trade/FlatMaterialData.h
@@ -63,6 +63,7 @@ class MAGNUM_TRADE_EXPORT FlatMaterialData: public MaterialData {
          * @ref MaterialAttribute::BaseColorTexture or
          * @ref MaterialAttribute::DiffuseTexture attributes is present,
          * @cpp false @ce otherwise.
+         * @see @ref texture()
          */
         bool hasTexture() const;
 
@@ -77,6 +78,7 @@ class MAGNUM_TRADE_EXPORT FlatMaterialData: public MaterialData {
          * example a @ref MaterialAttribute::BaseColorTexture but only a
          * @ref MaterialAttribute::DiffuseTextureMatrix,
          * returns @cpp false @ce.
+         * @see @ref textureMatrix()
          */
         bool hasTextureTransformation() const;
 
@@ -87,15 +89,16 @@ class MAGNUM_TRADE_EXPORT FlatMaterialData: public MaterialData {
         /**
          * @brief Whether the material uses extra texture coordinate sets
          *
-         * Returns @cpp true @ce if the material is textured an a
+         * Returns @cpp true @ce if the material is textured and a
          * @ref MaterialAttribute::BaseColorTextureCoordinates,
          * @ref MaterialAttribute::DiffuseTextureCoordinates or
          * @ref MaterialAttribute::TextureCoordinates attribute matching the
          * texture is present and has a non-zero value, @cpp false @ce
          * otherwise. In particular, if there's for example a
-         * @ref MaterialAttribute::BaseColorTexture but
-         * only a @ref MaterialAttribute::DiffuseTextureCoordinates, returns
+         * @ref MaterialAttribute::BaseColorTexture but only a
+         * @ref MaterialAttribute::DiffuseTextureCoordinates, returns
          * @cpp false @ce.
+         * @see @ref textureCoordinates()
          */
         bool hasTextureCoordinates() const;
 
diff --git a/src/Magnum/Trade/MaterialData.h b/src/Magnum/Trade/MaterialData.h
index 0ef7d113a..1022328f3 100644
--- a/src/Magnum/Trade/MaterialData.h
+++ b/src/Magnum/Trade/MaterialData.h
@@ -2044,7 +2044,7 @@ class MAGNUM_TRADE_EXPORT MaterialData {
          * Convenience access to the @ref MaterialAttribute::LayerFactorTextureCoordinates
          * / @ref MaterialAttribute::TextureCoordinates attributes in given
          * layer or a @ref MaterialAttribute::TextureCoordinates attribute in
-         * the base material. If not present, the default is @cpp 0 @ce.
+         * the base material. If neither is present, the default is @cpp 0 @ce.
          * Available only if the @ref MaterialAttribute::LayerFactorTexture
          * attribute is present. The @p layer is expected to exist.
          * @see @ref hasLayer(), @ref hasAttribute()
diff --git a/src/Magnum/Trade/PbrClearCoatMaterialData.h b/src/Magnum/Trade/PbrClearCoatMaterialData.h
index b2f1c1a39..df7f526eb 100644
--- a/src/Magnum/Trade/PbrClearCoatMaterialData.h
+++ b/src/Magnum/Trade/PbrClearCoatMaterialData.h
@@ -95,7 +95,8 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          * @ref MaterialAttribute::NormalTextureMatrix or
          * @ref MaterialAttribute::TextureMatrix attributes are present in this
          * layer or if @ref MaterialAttribute::TextureMatrix is present in the
-         * base material, @cpp false @ce otherwise
+         * base material, @cpp false @ce otherwise.
+         * @see @ref hasCommonTextureTransformation()
          */
         bool hasTextureTransformation() const;
 
@@ -108,6 +109,7 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          * otherwise. In particular, returns @cpp true @ce also if there's no
          * texture transformation at all. Use @ref hasTextureTransformation()
          * to distinguish that case.
+         * @see @ref commonTextureMatrix()
          */
         bool hasCommonTextureTransformation() const;
 
@@ -122,6 +124,7 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          * this material and have a non-zero value or if
          * @ref MaterialAttribute::TextureCoordinates is present in the base
          * material and has a non-zero value, @cpp false @ce otherwise.
+         * @see @ref hasCommonTextureCoordinates()
          */
         bool hasTextureCoordinates() const;
 
@@ -135,6 +138,7 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          * otherwise. In particular, returns @cpp true @ce also if there's no
          * extra texture coordinate set used at all. Use
          * @ref hasTextureCoordinates() to distinguish that case.
+         * @see @ref commonTextureCoordinates()
          */
         bool hasCommonTextureCoordinates() const;
 
@@ -154,7 +158,7 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          *
          * Available only if @ref MaterialAttribute::RoughnessTexture is
          * present in this layer. Meant to be multiplied with @ref roughness().
-         * @see @ref AbstractImporter::texture()
+         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
          */
         UnsignedInt roughnessTexture() const;
 
@@ -260,7 +264,7 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
          * @brief Common texture coordinate transformation matrix for all textures
          *
          * Expects that @ref hasCommonTextureTransformation() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a matrix that's the same for all of
          * @ref layerFactorTextureMatrix(), @ref roughnessTextureMatrix() and
          * @ref normalTextureMatrix() where a texture is present. If no texture
          * is present, returns an identity matrix.
@@ -268,13 +272,14 @@ class MAGNUM_TRADE_EXPORT PbrClearCoatMaterialData: public MaterialLayerData<Mat
         Matrix3 commonTextureMatrix() const;
 
         /**
-         * @brief Common texture coordinate set index for all textures
+         * @brief Common texture coordinate set for all textures
          *
          * Expects that @ref hasCommonTextureCoordinates() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
-         * @ref layerFactorTextureCoordinates(), @ref roughnessTextureCoordinates()
-         * and @ref normalTextureCoordinates() where a texture is present. If
-         * no texture is present, returns @cpp 0 @ce.
+         * returns a coordinate set that's the same for all of
+         * @ref layerFactorTextureCoordinates(),
+         * @ref roughnessTextureCoordinates() and
+         * @ref normalTextureCoordinates() where a texture is present. If no
+         * texture is present, returns @cpp 0 @ce.
          */
         UnsignedInt commonTextureCoordinates() const;
 };
diff --git a/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.cpp b/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.cpp
index c2101545a..c7d821130 100644
--- a/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.cpp
+++ b/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.cpp
@@ -126,7 +126,7 @@ bool PbrMetallicRoughnessMaterialData::hasTextureTransformation() const {
         hasAttribute(MaterialAttribute::RoughnessTextureMatrix) ||
         hasAttribute(MaterialAttribute::NormalTextureMatrix) ||
         hasAttribute(MaterialAttribute::OcclusionTextureMatrix) ||
-        hasAttribute(MaterialAttribute::EmissiveTextureMatrix);;
+        hasAttribute(MaterialAttribute::EmissiveTextureMatrix);
 }
 
 bool PbrMetallicRoughnessMaterialData::hasCommonTextureTransformation() const {
diff --git a/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.h b/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.h
index 8af5197cc..c7fc57ab5 100644
--- a/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.h
+++ b/src/Magnum/Trade/PbrMetallicRoughnessMaterialData.h
@@ -62,7 +62,8 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * @ref MaterialAttribute::MetalnessTexture or
          * @ref MaterialAttribute::NoneRoughnessMetallicTexture attributes is
          * present, @cpp false @ce otherwise.
-         * @see @ref hasRoughnessTexture(), @ref hasNoneRoughnessMetallicTexture()
+         * @see @ref metalnessTexture(), @ref hasRoughnessTexture(),
+         *      @ref hasNoneRoughnessMetallicTexture()
          */
         bool hasMetalnessTexture() const;
 
@@ -73,7 +74,8 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * @ref MaterialAttribute::RoughnessTexture or
          * @ref MaterialAttribute::NoneRoughnessMetallicTexture attributes is
          * present, @cpp false @ce otherwise.
-         * @see @ref hasMetalnessTexture(), @ref hasNoneRoughnessMetallicTexture()
+         * @see @ref roughnessTexture(), @ref hasMetalnessTexture(),
+         *      @ref hasNoneRoughnessMetallicTexture()
          */
         bool hasRoughnessTexture() const;
 
@@ -260,6 +262,7 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * the same value, @cpp false @ce otherwise. In particular, returns
          * @cpp true @ce also if there's no texture transformation at all. Use
          * @ref hasTextureTransformation() to distinguish that case.
+         * @see @ref commonTextureMatrix()
          */
         bool hasCommonTextureTransformation() const;
 
@@ -290,6 +293,7 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * returns @cpp true @ce also if there's no extra texture coordinate
          * set used at all. Use @ref hasTextureCoordinates() to distinguish
          * that case.
+         * @see @ref commonTextureCoordinates()
          */
         bool hasCommonTextureCoordinates() const;
 
@@ -492,10 +496,10 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * @brief Normal texture coordinate set
          *
          * Convenience access to the @ref MaterialAttribute::NormalTextureCoordinates
-         * / @ref MaterialAttribute::TextureCoordinates attributes. If neither is
-         * present, the default is @cpp 0 @ce. Available only if the material
-         * has @ref MaterialAttribute::NormalTexture.
-         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
+         * / @ref MaterialAttribute::TextureCoordinates attributes. If neither
+         * is present, the default is @cpp 0 @ce. Available only if the
+         * material has @ref MaterialAttribute::NormalTexture.
+         * @see @ref hasAttribute()
          */
         UnsignedInt normalTextureCoordinates() const;
 
@@ -600,7 +604,7 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
          * @brief Common texture coordinate transformation matrix for all textures
          *
          * Expects that @ref hasCommonTextureTransformation() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a matrix that's the same for all of
          * @ref baseColorTextureMatrix(), @ref metalnessTextureMatrix(),
          * @ref roughnessTextureMatrix(), @ref normalTextureMatrix(),
          * @ref occlusionTextureMatrix() and @ref emissiveTextureMatrix() where
@@ -610,7 +614,7 @@ class MAGNUM_TRADE_EXPORT PbrMetallicRoughnessMaterialData: public MaterialData
         Matrix3 commonTextureMatrix() const;
 
         /**
-         * @brief Common texture coordinate set index for all textures
+         * @brief Common texture coordinate set for all textures
          *
          * Expects that @ref hasCommonTextureCoordinates() is @cpp true @ce;
          * returns a coordinate set index that's the same for all of
diff --git a/src/Magnum/Trade/PbrSpecularGlossinessMaterialData.h b/src/Magnum/Trade/PbrSpecularGlossinessMaterialData.h
index dde03b205..650edb298 100644
--- a/src/Magnum/Trade/PbrSpecularGlossinessMaterialData.h
+++ b/src/Magnum/Trade/PbrSpecularGlossinessMaterialData.h
@@ -62,7 +62,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * @ref MaterialAttribute::SpecularTexture or
          * @ref MaterialAttribute::SpecularGlossinessTexture attributes is
          * present, @cpp false @ce otherwise.
-         * @see @ref hasGlossinessTexture(),
+         * @see @ref specularTexture(), @ref hasGlossinessTexture(),
          *      @ref hasSpecularGlossinessTexture()
          */
         bool hasSpecularTexture() const;
@@ -74,7 +74,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * @ref MaterialAttribute::GlossinessTexture or
          * @ref MaterialAttribute::SpecularGlossinessTexture attributes is
          * present, @cpp false @ce otherwise.
-         * @see @ref hasSpecularTexture(),
+         * @see @ref glossinessTexture(), @ref hasSpecularTexture(),
          *      @ref hasSpecularGlossinessTexture()
          */
         bool hasGlossinessTexture() const;
@@ -130,6 +130,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * the same value, @cpp false @ce otherwise. In particular, returns
          * @cpp true @ce also if there's no texture transformation at all. Use
          * @ref hasTextureTransformation() to distinguish that case.
+         * @see @ref commonTextureMatrix()
          */
         bool hasCommonTextureTransformation() const;
 
@@ -145,6 +146,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * @ref MaterialAttribute::EmissiveTextureCoordinates or
          * @ref MaterialAttribute::TextureCoordinates attributes is present and
          * has a non-zero value, @cpp false @ce otherwise.
+         * @see @ref hasCommonTextureCoordinates()
          */
         bool hasTextureCoordinates() const;
 
@@ -159,11 +161,12 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * returns @cpp true @ce also if there's no extra texture coordinate
          * set used at all. Use @ref hasTextureCoordinates() to distinguish
          * that case.
+         * @see @ref commonTextureCoordinates()
          */
         bool hasCommonTextureCoordinates() const;
 
         /**
-         * @brief Base color
+         * @brief Diffuse color
          *
          * Convenience access to the @ref MaterialAttribute::DiffuseColor
          * attribute. If not present, the default is @cpp 0xffffffff_srgbaf @ce.
@@ -174,7 +177,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
         Color4 diffuseColor() const;
 
         /**
-         * @brief Base color texture ID
+         * @brief Diffuse texture ID
          *
          * Available only if @ref MaterialAttribute::DiffuseTexture is
          * present. Meant to be multiplied with @ref diffuseColor().
@@ -183,7 +186,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
         UnsignedInt diffuseTexture() const;
 
         /**
-         * @brief Base color texture coordinate transformation matrix
+         * @brief Diffuse texture coordinate transformation matrix
          *
          * Convenience access to the @ref MaterialAttribute::DiffuseTextureMatrix
          * / @ref MaterialAttribute::TextureMatrix attributes. If neither is
@@ -194,7 +197,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
         Matrix3 diffuseTextureMatrix() const;
 
         /**
-         * @brief Base color texture coordinate set
+         * @brief Diffuse texture coordinate set
          *
          * Convenience access to the @ref MaterialAttribute::DiffuseTextureCoordinates
          * / @ref MaterialAttribute::TextureCoordinates attributes. If neither is
@@ -404,7 +407,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * / @ref MaterialAttribute::TextureMatrix attributes. If neither is
          * present, the default is an identity matrix. Available only if the
          * material has @ref MaterialAttribute::OcclusionTexture.
-         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
+         * @see @ref hasAttribute()
          */
         Matrix3 occlusionTextureMatrix() const;
 
@@ -415,7 +418,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * / @ref MaterialAttribute::TextureCoordinates attributes. If neither is
          * present, the default is @cpp 0 @ce. Available only if the material
          * has @ref MaterialAttribute::OcclusionTexture.
-         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
+         * @see @ref hasAttribute()
          */
         UnsignedInt occlusionTextureCoordinates() const;
 
@@ -449,7 +452,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * / @ref MaterialAttribute::TextureMatrix attributes. If neither is
          * present, the default is an identity matrix. Available only if the
          * material has @ref MaterialAttribute::EmissiveTexture.
-         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
+         * @see @ref hasAttribute()
          */
         Matrix3 emissiveTextureMatrix() const;
 
@@ -460,7 +463,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * / @ref MaterialAttribute::TextureCoordinates attributes. If neither
          * is present, the default is @cpp 0 @ce. Available only if the
          * material has @ref MaterialAttribute::EmissiveTexture.
-         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
+         * @see @ref hasAttribute()
          */
         UnsignedInt emissiveTextureCoordinates() const;
 
@@ -468,7 +471,7 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
          * @brief Common texture coordinate transformation matrix for all textures
          *
          * Expects that @ref hasCommonTextureTransformation() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a matrix that's the same for all of
          * @ref diffuseTextureMatrix(), @ref specularTextureMatrix(),
          * @ref glossinessTextureMatrix(), @ref normalTextureMatrix(),
          * @ref occlusionTextureMatrix() and @ref emissiveTextureMatrix() where
@@ -478,15 +481,15 @@ class MAGNUM_TRADE_EXPORT PbrSpecularGlossinessMaterialData: public MaterialData
         Matrix3 commonTextureMatrix() const;
 
         /**
-         * @brief Common texture coordinate set index for all textures
+         * @brief Common texture coordinate set for all textures
          *
          * Expects that @ref hasCommonTextureCoordinates() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a coordinate set that's the same for all of
          * @ref diffuseTextureCoordinates(), @ref specularTextureCoordinates(),
-         * @ref glossinessTextureCoordinates(), @ref normalTextureCoordinates(),
-         * @ref occlusionTextureCoordinates() and @ref emissiveTextureCoordinates()
-         * where a texture is present. If no texture is present, returns
-         * @cpp 0 @ce.
+         * @ref glossinessTextureCoordinates(),
+         * @ref normalTextureCoordinates(), @ref occlusionTextureCoordinates()
+         * and @ref emissiveTextureCoordinates() where a texture is present. If
+         * no texture is present, returns @cpp 0 @ce.
          */
         UnsignedInt commonTextureCoordinates() const;
 };
diff --git a/src/Magnum/Trade/PhongMaterialData.h b/src/Magnum/Trade/PhongMaterialData.h
index b49872228..5bdfdff88 100644
--- a/src/Magnum/Trade/PhongMaterialData.h
+++ b/src/Magnum/Trade/PhongMaterialData.h
@@ -267,6 +267,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public MaterialData {
          * same value, @cpp false @ce otherwise. In particular, returns
          * @cpp true @ce also if there's no texture transformation at all. Use
          * @ref hasTextureTransformation() to distinguish that case.
+         * @see @ref commonTextureMatrix()
          */
         bool hasCommonTextureTransformation() const;
 
@@ -296,6 +297,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public MaterialData {
          * returns @cpp true @ce also if there's no extra texture coordinate
          * set used at all. Use @ref hasTextureCoordinates() to distinguish
          * that case.
+         * @see @ref commonTextureCoordinates()
          */
         bool hasCommonTextureCoordinates() const;
 
@@ -335,7 +337,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public MaterialData {
          *
          * Available only if @ref MaterialAttribute::AmbientTexture is
          * present. Meant to be multiplied with @ref ambientColor().
-         * @see @ref hasAttribute()
+         * @see @ref hasAttribute(), @ref AbstractImporter::texture()
          */
         UnsignedInt ambientTexture() const;
 
@@ -572,7 +574,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public MaterialData {
          * @m_since_latest
          *
          * Expects that @ref hasCommonTextureTransformation() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a matrix that's the same for all of
          * @ref ambientTextureMatrix(), @ref diffuseTextureMatrix(),
          * @ref specularTextureMatrix() and @ref normalTextureMatrix() where a
          * texture is present. If no texture is present, returns an identity
@@ -595,15 +597,15 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public MaterialData {
         #endif
 
         /**
-         * @brief Common texture coordinate set index for all textures
+         * @brief Common texture coordinate set for all textures
          * @m_since_latest
          *
          * Expects that @ref hasCommonTextureCoordinates() is @cpp true @ce;
-         * returns a coordinate set index that's the same for all of
+         * returns a coordinate set that's the same for all of
          * @ref ambientTextureCoordinates(), @ref diffuseTextureCoordinates(),
-         * @ref specularTextureCoordinates() and @ref normalTextureCoordinates()
-         * where a texture is present. If no texture is present, returns
-         * @cpp 0 @ce.
+         * @ref specularTextureCoordinates() and
+         * @ref normalTextureCoordinates() where a texture is present. If no
+         * texture is present, returns @cpp 0 @ce.
          */
         UnsignedInt commonTextureCoordinates() const;