Doc++

All places were already consistently using "expected to <stuff>"
describing expectations backed by assertions, except for the Primitives
library. Fix that, plus random other doc fixes.

src/Magnum/GL/Attribute.h

@@ -169,8 +169,8 @@ template<UnsignedInt location, class T> 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

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
 

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);
 

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);
 

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

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

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

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 <Corrade/Containers/EnumSet.h>
@@ -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

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 <Corrade/Containers/EnumSet.h>
@@ -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

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 <Corrade/Containers/EnumSet.h>
@@ -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.

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 <Corrade/Containers/EnumSet.h>
@@ -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.

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 <Corrade/Containers/EnumSet.h>

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 <Corrade/Containers/EnumSet.h>

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 <Corrade/Containers/EnumSet.h>

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 <Corrade/Containers/EnumSet.h>
@@ -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