From 856d9c835b7d85b41c93f4a4d57f01820368d3f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 21 May 2025 10:35:23 +0200 Subject: [PATCH] Doc++ All places were already consistently using "expected to " describing expectations backed by assertions, except for the Primitives library. Fix that, plus random other doc fixes. --- src/Magnum/GL/Attribute.h | 4 +-- src/Magnum/MeshTools/Compile.h | 2 +- src/Magnum/Platform/AbstractXApplication.h | 8 ++--- src/Magnum/Platform/AndroidApplication.h | 8 ++--- src/Magnum/Platform/EmscriptenApplication.h | 8 ++--- src/Magnum/Platform/GlfwApplication.h | 8 ++--- src/Magnum/Platform/Sdl2Application.h | 8 ++--- src/Magnum/Primitives/Capsule.h | 36 ++++++++++----------- src/Magnum/Primitives/Circle.h | 13 +++++--- src/Magnum/Primitives/Cone.h | 12 +++---- src/Magnum/Primitives/Cylinder.h | 14 ++++---- src/Magnum/Primitives/Grid.h | 2 +- src/Magnum/Primitives/Plane.h | 2 +- src/Magnum/Primitives/Square.h | 2 +- src/Magnum/Primitives/UVSphere.h | 16 ++++----- 15 files changed, 73 insertions(+), 70 deletions(-) diff --git a/src/Magnum/GL/Attribute.h b/src/Magnum/GL/Attribute.h index 3a59f9861..023f5a6f9 100644 --- a/src/Magnum/GL/Attribute.h +++ b/src/Magnum/GL/Attribute.h @@ -169,8 +169,8 @@ template class Attribute { #ifndef MAGNUM_TARGET_GLES /** * Four components with BGRA ordering. Only for four-component - * float vector type. Must be used along with @ref DataType::UnsignedByte - * and @ref DataOption::Normalized. + * float vector type. Must be used along with + * @ref DataType::UnsignedByte and @ref DataOption::Normalized. * @m_keywords{GL_BGRA} * @requires_gl32 Extension @gl_extension{ARB,vertex_array_bgra} * @requires_gl Only RGBA component ordering is supported in OpenGL diff --git a/src/Magnum/MeshTools/Compile.h b/src/Magnum/MeshTools/Compile.h index d53f1fc4f..753356a75 100644 --- a/src/Magnum/MeshTools/Compile.h +++ b/src/Magnum/MeshTools/Compile.h @@ -28,7 +28,7 @@ #ifdef MAGNUM_TARGET_GL /** @file - * @brief Function @ref Magnum::MeshTools::compile() + * @brief Enum @ref Magnum::MeshTools::CompileFlag, enum set @ref Magnum::MeshTools::CompileFlags, function @ref Magnum::MeshTools::compile(), @ref Magnum::MeshTools::compiledPerVertexJointCount() */ #endif diff --git a/src/Magnum/Platform/AbstractXApplication.h b/src/Magnum/Platform/AbstractXApplication.h index 131d04bd7..f585ffaf9 100644 --- a/src/Magnum/Platform/AbstractXApplication.h +++ b/src/Magnum/Platform/AbstractXApplication.h @@ -207,10 +207,10 @@ class AbstractXApplication { * @param configuration Application configuration * @param glConfiguration OpenGL context configuration * - * Must be called only if the context wasn't created by the constructor - * itself, i.e. when passing @ref NoCreate to it. Error message is - * printed and the program exits if the context cannot be created, see - * @ref tryCreate() for an alternative. + * Must be called if and only if the context wasn't created by the + * constructor itself, i.e. when passing @ref NoCreate to it. Error + * message is printed and the program exits if the context cannot be + * created, see @ref tryCreate() for an alternative. */ void create(const Configuration& configuration, const GLConfiguration& glConfiguration); diff --git a/src/Magnum/Platform/AndroidApplication.h b/src/Magnum/Platform/AndroidApplication.h index d2a7aa3e6..75cd494ef 100644 --- a/src/Magnum/Platform/AndroidApplication.h +++ b/src/Magnum/Platform/AndroidApplication.h @@ -304,10 +304,10 @@ class AndroidApplication { * @param configuration Application configuration * @param glConfiguration OpenGL context configuration * - * Must be called only if the context wasn't created by the constructor - * itself, i.e. when passing @ref NoCreate to it. Error message is - * printed and the program exits if the context cannot be created, see - * @ref tryCreate() for an alternative. + * Must be called if and only if the context wasn't created by the + * constructor itself, i.e. when passing @ref NoCreate to it. Error + * message is printed and the program exits if the context cannot be + * created, see @ref tryCreate() for an alternative. */ void create(const Configuration& configuration, const GLConfiguration& glConfiguration); diff --git a/src/Magnum/Platform/EmscriptenApplication.h b/src/Magnum/Platform/EmscriptenApplication.h index 8f55bea08..4fa8edae4 100644 --- a/src/Magnum/Platform/EmscriptenApplication.h +++ b/src/Magnum/Platform/EmscriptenApplication.h @@ -492,10 +492,10 @@ class EmscriptenApplication { * @param configuration Application configuration * @param glConfiguration WebGL context configuration * - * Must be called only if the context wasn't created by the constructor - * itself, i.e. when passing @ref NoCreate to it. Error message is - * printed and the program exits if the context cannot be created, see - * @ref tryCreate() for an alternative. + * Must be called if and only if the context wasn't created by the + * constructor itself, i.e. when passing @ref NoCreate to it. Error + * message is printed and the program exits if the context cannot be + * created, see @ref tryCreate() for an alternative. * * @note This function is available only if Magnum is compiled with * @ref MAGNUM_TARGET_GL enabled (done by default). See diff --git a/src/Magnum/Platform/GlfwApplication.h b/src/Magnum/Platform/GlfwApplication.h index a7310cb32..e618ee0ad 100644 --- a/src/Magnum/Platform/GlfwApplication.h +++ b/src/Magnum/Platform/GlfwApplication.h @@ -381,10 +381,10 @@ class GlfwApplication { * @param configuration Application configuration * @param glConfiguration OpenGL context configuration * - * Must be called only if the context wasn't created by the constructor - * itself, i.e. when passing @ref NoCreate to it. Error message is - * printed and the program exits if the context cannot be created, see - * @ref tryCreate() for an alternative. + * Must be called if and only if the context wasn't created by the + * constructor itself, i.e. when passing @ref NoCreate to it. Error + * message is printed and the program exits if the context cannot be + * created, see @ref tryCreate() for an alternative. * * On desktop GL, if version is not specified in @p glConfiguration, * the application first tries to create core context (OpenGL 3.2+) and diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index bb2eb7d4b..4145fc710 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -804,10 +804,10 @@ class Sdl2Application { * @param configuration Application configuration * @param glConfiguration OpenGL context configuration * - * Must be called only if the context wasn't created by the constructor - * itself, i.e. when passing @ref NoCreate to it. Error message is - * printed and the program exits if the context cannot be created, see - * @ref tryCreate() for an alternative. + * Must be called if and only if the context wasn't created by the + * constructor itself, i.e. when passing @ref NoCreate to it. Error + * message is printed and the program exits if the context cannot be + * created, see @ref tryCreate() for an alternative. * * On desktop GL, if version is not specified in @p glConfiguration, * the application first tries to create core context (OpenGL 3.2+ on diff --git a/src/Magnum/Primitives/Capsule.h b/src/Magnum/Primitives/Capsule.h index 0fb69b581..c4b749e47 100644 --- a/src/Magnum/Primitives/Capsule.h +++ b/src/Magnum/Primitives/Capsule.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::capsule2DWireframe(), @ref Magnum::Primitives::capsule3DSolid(), @ref Magnum::Primitives::capsule3DWireframe() + * @brief Enum @ref Magnum::Primitives::CapsuleFlag, enum set @ref Magnum::Primitives::CapsuleFlags, function @ref Magnum::Primitives::capsule2DWireframe(), @ref Magnum::Primitives::capsule3DSolid(), @ref Magnum::Primitives::capsule3DWireframe() */ #include @@ -40,11 +40,11 @@ namespace Magnum { namespace Primitives { /** @brief Wireframe 2D capsule -@param hemisphereRings Number of (line) rings for each hemisphere. Must be - larger or equal to @cpp 1 @ce. -@param cylinderRings Number of (line) rings for cylinder. Must be larger or - equal to @cpp 1 @ce. -@param halfLength Half the length of cylinder part +@param hemisphereRings Number of (line) rings for each hemisphere. Expected to + be larger or equal to @cpp 1 @ce. +@param cylinderRings Number of (line) rings for cylinder. Expected to be larger + or equal to @cpp 1 @ce. +@param halfLength Half the length of the cylinder part Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin, with hemispheres instead of caps. @ref MeshPrimitive::Lines with @@ -88,13 +88,13 @@ CORRADE_ENUMSET_OPERATORS(CapsuleFlags) /** @brief Solid 3D capsule -@param hemisphereRings Number of (face) rings for each hemisphere. Must be +@param hemisphereRings Number of (face) rings for each hemisphere. Expected to + be larger or equal to @cpp 1 @ce. +@param cylinderRings Number of (face) rings for cylinder. Expected to be larger or equal to @cpp 1 @ce. -@param cylinderRings Number of (face) rings for cylinder. Must be larger or - equal to @cpp 1 @ce. -@param segments Number of (face) segments. Must be larger or equal to - @cpp 3 @ce. -@param halfLength Half the length of cylinder part +@param segments Number of (face) segments. Expected to be larger or + equal to @cpp 3 @ce. +@param halfLength Half the length of the cylinder part @param flags Flags @m_since{2020,06} @@ -138,13 +138,13 @@ CORRADE_IGNORE_DEPRECATED_POP /** @brief Wireframe 3D capsule -@param hemisphereRings Number of (line) rings for each hemisphere. Must be +@param hemisphereRings Number of (line) rings for each hemisphere. Expected to + be larger or equal to @cpp 1 @ce. +@param cylinderRings Number of (line) rings for cylinder. Expected to be larger or equal to @cpp 1 @ce. -@param cylinderRings Number of (line) rings for cylinder. Must be larger or - equal to @cpp 1 @ce. -@param segments Number of line segments. Must be larger or equal to - @cpp 4 @ce and multiple of @cpp 4 @ce. -@param halfLength Half the length of cylinder part +@param segments Number of line segments. Expected to be larger or equal + to @cpp 4 @ce and multiple of @cpp 4 @ce. +@param halfLength Half the length of the cylinder part Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin, with hemispheres instead of caps. @ref MeshPrimitive::Lines with diff --git a/src/Magnum/Primitives/Circle.h b/src/Magnum/Primitives/Circle.h index 00d7f130b..a41079afe 100644 --- a/src/Magnum/Primitives/Circle.h +++ b/src/Magnum/Primitives/Circle.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::circle2DSolid(), @ref Magnum::Primitives::circle2DWireframe(), @ref Magnum::Primitives::circle3DSolid(), @ref Magnum::Primitives::circle3DWireframe() + * @brief Enum @ref Magnum::Primitives::Circle2DFlag, @ref Magnum::Primitives::Circle3DFlag, enum set @ref Magnum::Primitives::Circle2DFlags, @ref Magnum::Primitives::Circle3DFlags, function @ref Magnum::Primitives::circle2DSolid(), @ref Magnum::Primitives::circle2DWireframe(), @ref Magnum::Primitives::circle3DSolid(), @ref Magnum::Primitives::circle3DWireframe() */ #include @@ -72,7 +72,8 @@ enum class CORRADE_DEPRECATED_ENUM("use Circle2DFlags or Circle3DFlags instead") /** @brief Solid 2D circle -@param segments Number of segments. Must be greater or equal to @cpp 3 @ce. +@param segments Number of segments. Expected to be greater or equal to + @cpp 3 @ce. @param flags Flags @m_since{2020,06} @@ -101,7 +102,7 @@ CORRADE_IGNORE_DEPRECATED_POP /** @brief Wireframe 2D circle -@param segments Number of segments. Must be greater or equal to +@param segments Number of segments. Expected to be greater or equal to @cpp 3 @ce. Circle with radius @cpp 1.0f @ce, centered at origin. Non-indexed @@ -144,7 +145,8 @@ CORRADE_ENUMSET_OPERATORS(Circle3DFlags) /** @brief Solid 3D circle -@param segments Number of segments. Must be greater or equal to @cpp 3 @ce. +@param segments Number of segments. Expected to be greater or equal to + @cpp 3 @ce. @param flags Flags @m_since{2020,06} @@ -174,7 +176,8 @@ CORRADE_IGNORE_DEPRECATED_POP /** @brief Wireframe 3D circle -@param segments Number of segments. Must be greater or equal to @cpp 3 @ce. +@param segments Number of segments. Expected to be greater or equal to + @cpp 3 @ce. Circle on the XY plane with radius @cpp 1.0f @ce, centered at origin. Non-indexed @ref MeshPrimitive::LineLoop with @ref VertexFormat::Vector2 diff --git a/src/Magnum/Primitives/Cone.h b/src/Magnum/Primitives/Cone.h index b7699d473..76e16a88d 100644 --- a/src/Magnum/Primitives/Cone.h +++ b/src/Magnum/Primitives/Cone.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::coneSolid(), @ref Magnum::Primitives::coneWireframe() + * @brief Enum @ref Magnum::Primitives::ConeFlag, enum set @ref Magnum::Primitives::ConeFlags, function @ref Magnum::Primitives::coneSolid(), @ref Magnum::Primitives::coneWireframe() */ #include @@ -82,10 +82,10 @@ CORRADE_ENUMSET_OPERATORS(ConeFlags) /** @brief Solid 3D cone -@param rings Number of (face) rings. Must be larger or equal to +@param rings Number of (face) rings. Expected to be larger or equal to @cpp 1 @ce. -@param segments Number of (face) segments. Must be larger or equal to - @cpp 3 @ce. +@param segments Number of (face) segments. Expected to be larger or equal + to @cpp 3 @ce. @param halfLength Half the cone length @param flags Flags @@ -109,8 +109,8 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData coneSolid(UnsignedInt rings, UnsignedIn /** @brief Wireframe 3D cone -@param segments Number of (line) segments. Must be larger or equal to - @cpp 4 @ce and multiple of @cpp 4 @ce. +@param segments Number of (line) segments. Expected to be larger or equal + to @cpp 4 @ce and multiple of @cpp 4 @ce. @param halfLength Half the cone length Cone of radius @cpp 1.0f @ce along the Y axis, centered at origin. diff --git a/src/Magnum/Primitives/Cylinder.h b/src/Magnum/Primitives/Cylinder.h index 19f903824..4f9b41078 100644 --- a/src/Magnum/Primitives/Cylinder.h +++ b/src/Magnum/Primitives/Cylinder.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::cylinderSolid(), @ref Magnum::Primitives::cylinderWireframe() + * @brief Enum @ref Magnum::Primitives::CylinderFlag, enum set @ref Magnum::Primitives::CylinderFlags, function @ref Magnum::Primitives::cylinderSolid(), @ref Magnum::Primitives::cylinderWireframe() */ #include @@ -81,10 +81,10 @@ CORRADE_ENUMSET_OPERATORS(CylinderFlags) /** @brief Solid 3D cylinder -@param rings Number of (face) rings. Must be larger or equal to +@param rings Number of (face) rings. Expected to be larger or equal to @cpp 1 @ce. -@param segments Number of (face) segments. Must be larger or equal to - @cpp 3 @ce. +@param segments Number of (face) segments. Expected to be larger or equal + to @cpp 3 @ce. @param halfLength Half the cylinder length @param flags Flags @@ -108,10 +108,10 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData cylinderSolid(UnsignedInt rings, Unsign /** @brief Wireframe 3D cylinder -@param rings Number of (line) rings. Must be larger or equal to +@param rings Number of (line) rings. Expected to be larger or equal to @cpp 1 @ce. -@param segments Number of (line) segments. Must be larger or equal to - @cpp 4 @ce and multiple of @cpp 4 @ce. +@param segments Number of (line) segments. Expected to be larger or equal + to @cpp 4 @ce and multiple of @cpp 4 @ce. @param halfLength Half the cylinder length Cylinder of radius @cpp 1.0f @ce along the Y axis, centerd at origin. diff --git a/src/Magnum/Primitives/Grid.h b/src/Magnum/Primitives/Grid.h index ec518eb4e..b13ddcb11 100644 --- a/src/Magnum/Primitives/Grid.h +++ b/src/Magnum/Primitives/Grid.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::grid3DSolid(), @ref Magnum::Primitives::grid3DWireframe() + * @brief Enum @ref Magnum::Primitives::GridFlag, enum set @ref Magnum::Primitives::GridFlags, function @ref Magnum::Primitives::grid3DSolid(), @ref Magnum::Primitives::grid3DWireframe() */ #include diff --git a/src/Magnum/Primitives/Plane.h b/src/Magnum/Primitives/Plane.h index e4036f08a..012d8b363 100644 --- a/src/Magnum/Primitives/Plane.h +++ b/src/Magnum/Primitives/Plane.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::planeSolid(), @ref Magnum::Primitives::planeWireframe() + * @brief Enum @ref Magnum::Primitives::PlaneFlag, enum set @ref Magnum::Primitives::PlaneFlags, function @ref Magnum::Primitives::planeSolid(), @ref Magnum::Primitives::planeWireframe() */ #include diff --git a/src/Magnum/Primitives/Square.h b/src/Magnum/Primitives/Square.h index 4499ee1c8..ac05b9c38 100644 --- a/src/Magnum/Primitives/Square.h +++ b/src/Magnum/Primitives/Square.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Function @ref Magnum::Primitives::squareSolid(), @ref Magnum::Primitives::squareWireframe() + * @brief Enum @ref Magnum::Primitives::SquareFlag, enum set @ref Magnum::Primitives::SquareFlags, function @ref Magnum::Primitives::squareSolid(), @ref Magnum::Primitives::squareWireframe() */ #include diff --git a/src/Magnum/Primitives/UVSphere.h b/src/Magnum/Primitives/UVSphere.h index 45cb39987..992055776 100644 --- a/src/Magnum/Primitives/UVSphere.h +++ b/src/Magnum/Primitives/UVSphere.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Class @ref Magnum::Primitives::uvSphereSolid(), @ref Magnum::Primitives::uvSphereWireframe() + * @brief Enum @ref Magnum::Primitives::UVSphereFlag, enum set @ref Magnum::Primitives::UVSphereFlags, function @ref Magnum::Primitives::uvSphereSolid(), @ref Magnum::Primitives::uvSphereWireframe() */ #include @@ -68,9 +68,9 @@ CORRADE_ENUMSET_OPERATORS(UVSphereFlags) /** @brief Solid 3D UV sphere -@param rings Number of (face) rings. Must be larger or equal to - @cpp 2 @ce. -@param segments Number of (face) segments. Must be larger or +@param rings Number of (face) rings. Expected to be larger or equal + to @cpp 2 @ce. +@param segments Number of (face) segments. Expected to be larger or equal to @cpp 3 @ce. @param flags Flags @m_since{2020,06} @@ -110,10 +110,10 @@ CORRADE_IGNORE_DEPRECATED_POP /** @brief Wireframe 3D UV sphere -@param rings Number of (line) rings. Must be larger or equal to - @cpp 2 @ce and multiple of @cpp 2 @ce. -@param segments Number of (line) segments. Must be larger or equal to - @cpp 4 @ce and multiple of @cpp 4 @ce. +@param rings Number of (line) rings. Expected to be larger or equal + to @cpp 2 @ce and multiple of @cpp 2 @ce. +@param segments Number of (line) segments. Expected to be larger or + equal to @cpp 4 @ce and multiple of @cpp 4 @ce. Sphere of radius @cpp 1.0f @ce, centered at origin. @ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3