doc: strict ordering of sections in detailed documentation.

It makes sense, but this ordering also helps to avoid bug in Doxygen
1.8.6+ which merges next non-xrefitem section with the previous one (so
e.g. the TODO list contained the following @see block, which is not
desired).

doc/coding-style.dox

@@ -191,6 +191,18 @@ requirements.
 All classes and functions using those commands are cross-referenced in page
 @ref opengl-required-extensions.
 
+@subsection coding-style-documentation-ordering Section ordering
+
+In detailed documentation the text should be always first, the blocks are then
+ordered by their importance. Various @c \@note, @c \@attention and @c \@warning
+blocks to highlight some information are always first, then @c \@see block with
+links to related stuff, where related %Magnum functions are first and links to
+related GL API last, then various support information such as
+@c \@requires_glXX, @c \@requires_es_extension etc. (first desktop GL, then ES,
+then WebGL), after that @c \@deprecated_gl and @c \@deprecated information and
+@c \@todo, @c \@todoc and @c \@bug always last, as they are the least important
+and in most cases only for internal use.
+
 @section coding-style-unit-tests Unit tests
 
 All unit tests use Corrade's @ref Corrade::TestSuite "TestSuite".

src/Magnum/AbstractShaderProgram.h

@@ -350,8 +350,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} is
          * not available, returns `0`.
-         * @requires_gl Atomic counters are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_ATOMIC_COUNTER_BUFFER_SIZE}
+         * @requires_gl Atomic counters are not available in OpenGL ES.
          */
         static Int maxAtomicCounterBufferSize();
 
@@ -361,8 +361,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,compute_shader} is not
          * available, returns `0`.
-         * @requires_gl Compute shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_COMPUTE_SHARED_MEMORY_SIZE}
+         * @requires_gl Compute shaders are not available in OpenGL ES.
          */
         static Int maxComputeSharedMemorySize();
 
@@ -372,8 +372,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,compute_shader} is not
          * available, returns `0`.
-         * @requires_gl Compute shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_COMPUTE_WORK_GROUP_INVOCATIONS}
+         * @requires_gl Compute shaders are not available in OpenGL ES.
          */
         static Int maxComputeWorkGroupInvocations();
 
@@ -385,8 +385,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_image_load_store}
          * is not available, returns `0`.
-         * @requires_gl %Image load/store is not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_IMAGE_UNITS}
+         * @requires_gl %Image load/store is not available in OpenGL ES.
          */
         static Int maxImageUnits();
 
@@ -396,8 +396,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_image_load_store}
          * is not available, returns `0`.
-         * @requires_gl %Image load/store is not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_IMAGE_SAMPLES}
+         * @requires_gl %Image load/store is not available in OpenGL ES.
          */
         static Int maxImageSamples();
 
@@ -408,8 +408,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * OpenGL calls. If neither @extension{ARB,shader_image_load_store}
          * nor @extension{ARB,shader_storage_buffer_object} extension is
          * available, returns `0`.
-         * @requires_gl %Image load/store is not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_COMBINED_SHADER_OUTPUT_RESOURCES}
+         * @requires_gl %Image load/store is not available in OpenGL ES.
          */
         static Int maxCombinedShaderOutputResources();
 
@@ -419,8 +419,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_storage_buffer_object}
          * is not available, returns `0`.
-         * @requires_gl %Shader storage is not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_SHADER_STORAGE_BLOCK_SIZE}
+         * @requires_gl %Shader storage is not available in OpenGL ES.
          */
         static Long maxShaderStorageBlockSize();
         #endif
@@ -432,8 +432,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,uniform_buffer_object}
          * is not available, returns `0`.
-         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          * @see @fn_gl{Get} with @def_gl{MAX_UNIFORM_BLOCK_SIZE}
+         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          */
         static Int maxUniformBlockSize();
         #endif
@@ -445,8 +445,8 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,explicit_uniform_location}
          * is not available, returns `0`.
-         * @requires_gl Explicit uniform location is not supported in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_UNIFORM_LOCATIONS}
+         * @requires_gl Explicit uniform location is not supported in OpenGL ES.
          */
         static Int maxUniformLocations();
         #endif
@@ -458,9 +458,9 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{EXT,gpu_shader4} is not
          * available, returns `0`.
+         * @see @fn_gl{Get} with @def_gl{MIN_PROGRAM_TEXEL_OFFSET}
          * @requires_gles30 %Texture lookup with offset is not available in
          *      OpenGL ES 2.0.
-         * @see @fn_gl{Get} with @def_gl{MIN_PROGRAM_TEXEL_OFFSET}
          */
         static Int minTexelOffset();
 
@@ -470,9 +470,9 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{EXT,gpu_shader4} is not
          * available, returns `0`.
+         * @see @fn_gl{Get} with @def_gl{MAX_PROGRAM_TEXEL_OFFSET}
          * @requires_gles30 %Texture lookup with offset is not available in
          *      OpenGL ES 2.0.
-         * @see @fn_gl{Get} with @def_gl{MAX_PROGRAM_TEXEL_OFFSET}
          */
         static Int maxTexelOffset();
         #endif
@@ -613,11 +613,11 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          *
          * Binds attribute to location which is used later for binding vertex
          * buffers.
+         * @see @fn_gl{BindAttribLocation}
          * @deprecated_gl Preferred usage is to specify attribute location
          *      explicitly in the shader instead of using this function. See
          *      @ref AbstractShaderProgram-attribute-location "class documentation"
          *      for more information.
-         * @see @fn_gl{BindAttribLocation}
          */
         void bindAttributeLocation(UnsignedInt location, const std::string& name);
 
@@ -631,11 +631,11 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * Binds fragment data to location which is used later for framebuffer
          * operations. See also @ref Renderer::BlendFunction for more
          * information about using color input index.
+         * @see @fn_gl{BindFragDataLocationIndexed}
          * @deprecated_gl Preferred usage is to specify attribute location
          *      explicitly in the shader instead of using this function. See
          *      @ref AbstractShaderProgram-attribute-location "class documentation"
          *      for more information.
-         * @see @fn_gl{BindFragDataLocationIndexed}
          * @requires_gl33 %Extension @extension{ARB,blend_func_extended}
          * @requires_gl Multiple blend function inputs are not available in
          *      OpenGL ES.
@@ -672,11 +672,11 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject {
          * @brief Get uniform location
          * @param name          Uniform name
          *
+         * @see @fn_gl{GetUniformLocation}
          * @deprecated_gl Preferred usage is to specify uniform location
          *      explicitly in the shader instead of using this function. See
          *      @ref AbstractShaderProgram-uniform-location "class documentation"
          *      for more information.
-         * @see @fn_gl{GetUniformLocation}
          */
         Int uniformLocation(const std::string& name);
 

src/Magnum/Buffer.h

@@ -328,11 +328,11 @@ class MAGNUM_EXPORT Buffer: public AbstractObject {
         /**
          * @brief Memory mapping access
          *
-         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
-         *      instead, as it has more complete set of features.
          * @see @ref map(MapAccess), @ref mapSub()
          * @requires_es_extension %Extension @es_extension{OES,mapbuffer} or
          *      @es_extension{CHROMIUM,map_sub}
+         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
+         *      instead, as it has more complete set of features.
          */
         enum class MapAccess: GLenum {
             #ifndef MAGNUM_TARGET_GLES
@@ -610,11 +610,11 @@ class MAGNUM_EXPORT Buffer: public AbstractObject {
          * @brief Bind buffer
          * @param target    %Target
          *
+         * @see @fn_gl{BindBuffer}
          * @todo Allow binding to Target::ElementArray only if VAO is bound
          *      to avoid potential issues?
-         * @bug Binding to ElementArray if any VAO is active will corrupt the mesh
          * @todo Don't allow user to bind buffers?
-         * @see @fn_gl{BindBuffer}
+         * @bug Binding to ElementArray if any VAO is active will corrupt the mesh
          */
         void bind(Target target) { bind(target, _id); }
 
@@ -746,14 +746,14 @@ class MAGNUM_EXPORT Buffer: public AbstractObject {
          * If @extension{EXT,direct_state_access} is not available and the
          * buffer is not already bound somewhere, it is bound to hinted target
          * before the operation.
-         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
-         *      instead, as it has more complete set of features.
          * @see @ref minMapAlignment(), @ref unmap(), @ref setTargetHint(),
          *      @fn_gl{BindBuffer} and @fn_gl{MapBuffer} or
          *      @fn_gl_extension{MapNamedBuffer,EXT,direct_state_access}
          * @requires_es_extension %Extension @es_extension{OES,mapbuffer} in
          *      OpenGL ES 2.0, use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
          *      in OpenGL ES 3.0 instead.
+         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
+         *      instead, as it has more complete set of features.
          */
         void* map(MapAccess access);
 
@@ -767,14 +767,14 @@ class MAGNUM_EXPORT Buffer: public AbstractObject {
          *
          * If the buffer is not already bound somewhere, it is bound to hinted
          * target before the operation.
-         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
-         *      instead, as it has more complete set of features.
          * @see @ref unmapSub(), @ref setTargetHint(),
          *      @fn_gl_extension{MapBufferSubData,CHROMIUM,map_sub}
          * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
          *      @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
          *      instead.
          * @requires_es_extension %Extension @es_extension{CHROMIUM,map_sub}
+         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
+         *      instead, as it has more complete set of features.
          */
         void* mapSub(GLintptr offset, GLsizeiptr length, MapAccess access);
         #endif

src/Magnum/ColorFormat.h

@@ -85,10 +85,10 @@ enum class ColorFormat: GLenum {
     /**
      * Floating-point luminance channel. The value is used for all RGB
      * channels.
-     * @deprecated_gl Included for compatibility reasons only, use
-     *      @ref Magnum::ColorFormat::Red "ColorFormat::Red" instead.
      * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
      *      @ref Magnum::ColorFormat::Red "ColorFormat::Red" instead.
+     * @deprecated_gl Included for compatibility reasons only, use
+     *      @ref Magnum::ColorFormat::Red "ColorFormat::Red" instead.
      */
     Luminance = GL_LUMINANCE,
     #endif
@@ -110,10 +110,10 @@ enum class ColorFormat: GLenum {
     /**
      * Floating-point luminance and alpha channel. First value is used for all
      * RGB channels, second value is used for alpha channel.
-     * @deprecated_gl Included for compatibility reasons only, use
-     *      @ref Magnum::ColorFormat::RG "ColorFormat::RG" instead.
      * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
      *      @ref Magnum::ColorFormat::RG "ColorFormat::RG" instead.
+     * @deprecated_gl Included for compatibility reasons only, use
+     *      @ref Magnum::ColorFormat::RG "ColorFormat::RG" instead.
      */
     LuminanceAlpha = GL_LUMINANCE_ALPHA,
     #endif

src/Magnum/Math/Angle.h

@@ -157,9 +157,9 @@ Double cosine = Math::cos(60.0_deg);  // cosine = 0.5
 Double cosine = Math::cos(1.047_rad); // cosine = 0.5
 @endcode
 @see Magnum::operator""_deg(), operator""_degf(), operator""_rad()
-@todoc Make references explicit when Doxygen can link to operator""
 @note Not available on GCC < 4.7. Use @ref Deg::Deg(T) instead.
 @requires_gl Only single-precision types are available in OpenGL ES.
+@todoc Make references explicit when Doxygen can link to operator""
 */
 constexpr Deg<Double> operator "" _deg(long double value) { return Deg<Double>(value); }
 #endif
@@ -173,9 +173,9 @@ Float tangent = Math::tan(60.0_degf);  // tangent = 1.732f
 Float tangent = Math::tan(1.047_radf); // tangent = 1.732f
 @endcode
 @see Magnum::operator""_degf(), operator""_deg(), operator""_radf()
-@todoc Make references explicit when Doxygen can link to operator""
 @note Not available on GCC < 4.7. Use @ref Deg::Deg(T) instead.
 @requires_gl Only single-precision types are available in OpenGL ES.
+@todoc Make references explicit when Doxygen can link to operator""
 */
 constexpr Deg<Float> operator "" _degf(long double value) { return Deg<Float>(value); }
 #endif
@@ -218,8 +218,8 @@ template<class T> class Rad: public Unit<Rad, T> {
 
 See operator""_rad() for more information.
 @see Magnum::operator""_rad(), operator""_radf(), operator""_deg()
-@todoc Make references explicit when Doxygen can link to operator""
 @note Not available on GCC < 4.7. Use @ref Rad::Rad(T) instead.
+@todoc Make references explicit when Doxygen can link to operator""
 */
 constexpr Rad<Double> operator "" _rad(long double value) { return Rad<Double>(value); }
 #endif
@@ -229,8 +229,8 @@ constexpr Rad<Double> operator "" _rad(long double value) { return Rad<Double>(v
 
 See operator""_degf() for more information.
 @see Magnum::operator""_radf(), operator""_rad(), operator""_degf()
-@todoc Make references explicit when Doxygen can link to operator""
 @note Not available on GCC < 4.7. Use @ref Rad::Rad(T) instead.
+@todoc Make references explicit when Doxygen can link to operator""
 */
 constexpr Rad<Float> operator "" _radf(long double value) { return Rad<Float>(value); }
 #endif

src/Magnum/Math/BoolVector.h

@@ -106,8 +106,8 @@ template<std::size_t size> class BoolVector {
          * @brief Raw data
          * @return %Array of DataSize length
          *
-         * @todoc Make reference explicit when Doxygen can link to operator[]
          * @see operator[](), @ref set()
+         * @todoc Make reference explicit when Doxygen can link to operator[]
          */
         UnsignedByte* data() { return _data; }
         constexpr const UnsignedByte* data() const { return _data; } /**< @overload */

src/Magnum/MeshTools/CompressIndices.h

@@ -74,14 +74,13 @@ std::tuple<Containers::Array<char>, Mesh::IndexType, UnsignedInt, UnsignedInt> M
 @param usage    Index buffer usage
 @param indices  Index array
 
-@deprecated Use general-purpose
-    @ref Magnum::MeshTools::compressIndices(const std::vector<UnsignedInt>&) "compressIndices(const std::vector<UnsignedInt>&)"
-    instead.
-
 The same as @ref compressIndices(const std::vector<UnsignedInt>&), but this
 function writes the output to given buffer and calls @ref Mesh::setCount() and
 @ref Mesh::setIndexBuffer(), thus you don't need to do anything else for mesh
 index configuration.
+@deprecated Use general-purpose
+    @ref Magnum::MeshTools::compressIndices(const std::vector<UnsignedInt>&) "compressIndices(const std::vector<UnsignedInt>&)"
+    instead.
 */
 void MAGNUM_MESHTOOLS_EXPORT compressIndices(Mesh& mesh, Buffer& buffer, BufferUsage usage, const std::vector<UnsignedInt>& indices);
 #endif

src/Magnum/MeshTools/Interleave.h

@@ -186,10 +186,6 @@ template<class T, class ...U> void interleaveInto(Containers::ArrayReference<cha
 @param usage        Vertex buffer usage
 @param attributes   Attribute arrays and gaps
 
-@deprecated Use general-purpose
-    @ref Magnum::MeshTools::interleave(const T&...) "interleave(const T&...)"
-    instead.
-
 The same as @ref interleave(const T&, const U&...), but this function also
 writes the output to given array buffer. If given mesh is not indexed, it also
 updates vertex count in the mesh accordingly, so you don't have to call
@@ -199,6 +195,10 @@ updates vertex count in the mesh accordingly, so you don't have to call
     @ref Mesh::addVertexBuffer() on the mesh afterwards.
 
 @see @ref compressIndices(), @ref compile()
+
+@deprecated Use general-purpose
+    @ref Magnum::MeshTools::interleave(const T&...) "interleave(const T&...)"
+    instead.
 */
 template<class ...T> CORRADE_DEPRECATED("Use interleave(const T&...) instead") void interleave(Mesh& mesh, Buffer& buffer, BufferUsage usage, const T&... attributes) {
     if(!mesh.isIndexed()) mesh.setCount(Implementation::AttributeCount{}(attributes...));
@@ -208,16 +208,16 @@ template<class ...T> CORRADE_DEPRECATED("Use interleave(const T&...) instead") v
 /**
 @brief Write vertex attribute to array buffer and configure the mesh
 
-@deprecated Use general-purpose
-    @ref Magnum::MeshTools::interleave(const T&...) "interleave(const T&...)"
-    instead.
-
 Simplified specialization of the above function for only one attribute array,
 equivalent to the following:
 @code
 if(!mesh.isIndexed()) mesh.setCount(attribute.size());
 buffer.setData(attribute, usage);
 @endcode
+
+@deprecated Use general-purpose
+    @ref Magnum::MeshTools::interleave(const T&...) "interleave(const T&...)"
+    instead.
 */
 template<class T> CORRADE_DEPRECATED("Use interleave(const T&...) instead") typename std::enable_if<!std::is_convertible<T, std::size_t>::value, void>::type interleave(Mesh& mesh, Buffer& buffer, BufferUsage usage, const T& attribute) {
     if(!mesh.isIndexed()) mesh.setCount(attribute.size());

src/Magnum/Platform/NaClApplication.h

@@ -466,8 +466,8 @@ class NaClApplication::InputEvent {
         /**
          * @brief %Modifier
          *
-         * @todo AltGr + PP_INPUTEVENT_MODIFIER_ISKEYPAD, PP_INPUTEVENT_MODIFIER_ISAUTOREPEAT
          * @see @ref Modifiers, @ref modifiers()
+         * @todo AltGr + PP_INPUTEVENT_MODIFIER_ISKEYPAD, PP_INPUTEVENT_MODIFIER_ISAUTOREPEAT
          */
         enum class Modifier: std::uint32_t {
             Shift = PP_INPUTEVENT_MODIFIER_SHIFTKEY,    /**< Shift */
@@ -558,8 +558,8 @@ class NaClApplication::KeyEvent: public NaClApplication::InputEvent {
         /**
          * @brief Key
          *
-         * @todo Slash, percent, equal to be compatible with *XApplication
          * @see @ref key()
+         * @todo Slash, percent, equal to be compatible with *XApplication
          */
         enum class Key: std::uint32_t {
             Enter = 0x0D,               /**< Enter */

src/Magnum/Query.h

@@ -100,6 +100,8 @@ class MAGNUM_EXPORT AbstractQuery: public AbstractObject {
          *
          * Note that this function is blocking until the result is available.
          * See resultAvailable().
+         * @attention @ref Magnum::UnsignedLong "UnsignedLong" and @ref Magnum::Long "Long"
+         *      result type is not available in @ref MAGNUM_TARGET_WEBGL "WebGL".
          * @see @fn_gl{GetQueryObject} with @def_gl{QUERY_RESULT}
          * @requires_gl33 %Extension @extension{ARB,timer_query} for result
          *      type @ref Magnum::UnsignedInt "UnsignedInt" and @ref Magnum::Long
@@ -107,8 +109,6 @@ class MAGNUM_EXPORT AbstractQuery: public AbstractObject {
          * @requires_es_extension %Extension @es_extension{EXT,disjoint_timer_query}
          *      for result types @ref Magnum::Int "Int", @ref Magnum::UnsignedLong "UnsignedLong"
          *      @ref Magnum::Long "Long".
-         * @attention @ref Magnum::UnsignedLong "UnsignedLong" and @ref Magnum::Long "Long"
-         *      result type is not available in @ref MAGNUM_TARGET_WEBGL "WebGL".
          */
         template<class T> T result();
 
@@ -256,9 +256,9 @@ q.beginConditionalRender(SampleQuery::ConditionalRenderMode::Wait);
 q.endConditionalRender();
 @endcode
 
+@see @ref PrimitiveQuery, @ref TimeQuery
 @requires_gles30 %Extension @es_extension{EXT,occlusion_query_boolean} in
     OpenGL ES 2.0
-@see @ref PrimitiveQuery, @ref TimeQuery
 */
 class SampleQuery: public AbstractQuery {
     public:

src/Magnum/RenderbufferFormat.h

@@ -44,10 +44,10 @@ enum class RenderbufferFormat: GLenum {
     #ifndef MAGNUM_TARGET_GLES
     /**
      * Red component, normalized unsigned, size implementation-dependent.
-     * @deprecated_gl Prefer to use the exactly specified version of this
-     *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::R8".
      * @requires_gl30 %Extension @extension{ARB,texture_rg}
      * @requires_gl Use exactly specified format in OpenGL ES instead.
+     * @deprecated_gl Prefer to use the exactly specified version of this
+     *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::R8".
      */
     Red = GL_RED,
     #endif
@@ -68,10 +68,10 @@ enum class RenderbufferFormat: GLenum {
     /**
      * Red and green component, normalized unsigned, size
      * implementation-dependent.
-     * @deprecated_gl Prefer to use the exactly specified version of this
-     *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RG8".
      * @requires_gl30 %Extension @extension{ARB,texture_rg}
      * @requires_gl Use exactly specified format in OpenGL ES instead.
+     * @deprecated_gl Prefer to use the exactly specified version of this
+     *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RG8".
      */
     RG = GL_RG,
     #endif
@@ -91,9 +91,9 @@ enum class RenderbufferFormat: GLenum {
     #ifndef MAGNUM_TARGET_GLES
     /**
      * RGBA, normalized unsigned, size implementation-dependent.
+     * @requires_gl Use exactly specified format in OpenGL ES 2.0 instead.
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RGBA8".
-     * @requires_gl Use exactly specified format in OpenGL ES 2.0 instead.
      */
     RGBA = GL_RGBA,
     #endif
@@ -387,9 +387,9 @@ enum class RenderbufferFormat: GLenum {
     /**
      * Depth component, size implementation-dependent.
      * @todo is this allowed in core?
+     * @requires_gl Use exactly specified format in OpenGL ES instead.
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::DepthComponent16".
-     * @requires_gl Use exactly specified format in OpenGL ES instead.
      */
     DepthComponent = GL_DEPTH_COMPONENT,
     #endif
@@ -430,9 +430,9 @@ enum class RenderbufferFormat: GLenum {
     #ifndef MAGNUM_TARGET_GLES
     /**
      * Stencil index, size implementation-dependent.
+     * @requires_gl Use exactly specified format in OpenGL ES instead.
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::StencilIndex8".
-     * @requires_gl Use exactly specified format in OpenGL ES instead.
      */
     StencilIndex = GL_STENCIL_INDEX,
     #endif
@@ -469,9 +469,9 @@ enum class RenderbufferFormat: GLenum {
 
     /**
      * Depth and stencil component, size implementation-dependent.
+     * @requires_gl Use exactly specified format in OpenGL ES instead.
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::Depth24Stencil8".
-     * @requires_gl Use exactly specified format in OpenGL ES instead.
      */
     DepthStencil = GL_DEPTH_STENCIL,
     #endif

src/Magnum/Renderer.h

@@ -86,9 +86,9 @@ class MAGNUM_EXPORT Renderer {
 
             /**
              * Debug output
+             * @see @ref DebugMessage, @ref Feature::DebugOutputSynchronous
              * @requires_gl43 %Extension @extension{KHR,debug}
              * @requires_es_extension %Extension @es_extension{KHR,debug}
-             * @see @ref DebugMessage, @ref Feature::DebugOutputSynchronous
              */
             #ifndef MAGNUM_TARGET_GLES
             DebugOutput = GL_DEBUG_OUTPUT,
@@ -97,11 +97,11 @@ class MAGNUM_EXPORT Renderer {
             #endif
 
             /**
-             * Synchronous debug output. Has effect only if @ref Feature::DebugOutput
+             * Synchronous debug output. Has effect only if
-             * is enabled.
+             * @ref Feature::DebugOutput is enabled.
+             * @see @ref DebugMessage
              * @requires_gl43 %Extension @extension{KHR,debug}
              * @requires_es_extension %Extension @es_extension{KHR,debug}
-             * @see @ref DebugMessage
              */
             #ifndef MAGNUM_TARGET_GLES
             DebugOutputSynchronous = GL_DEBUG_OUTPUT_SYNCHRONOUS,

src/Magnum/Shader.h

@@ -122,8 +122,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,tessellation_shader}
          * is not available, returns `0`.
-         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_TESS_CONTROL_INPUT_COMPONENTS}
+         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          */
         static Int maxTessellationControlInputComponents();
 
@@ -133,8 +133,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,tessellation_shader}
          * is not available, returns `0`.
-         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_TESS_CONTROL_OUTPUT_COMPONENTS}
+         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          */
         static Int maxTessellationControlOutputComponents();
 
@@ -144,8 +144,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,tessellation_shader}
          * is not available, returns `0`.
-         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_TESS_CONTROL_TOTAL_OUTPUT_COMPONENTS}
+         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          */
         static Int maxTessellationControlTotalOutputComponents();
 
@@ -155,8 +155,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,tessellation_shader}
          * is not available, returns `0`.
-         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_TESS_EVALUATION_INPUT_COMPONENTS}
+         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          */
         static Int maxTessellationEvaluationInputComponents();
 
@@ -166,8 +166,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,tessellation_shader}
          * is not available, returns `0`.
-         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_TESS_EVALUATION_OUTPUT_COMPONENTS}
+         * @requires_gl Tessellation shaders are not available in OpenGL ES.
          */
         static Int maxTessellationEvaluationOutputComponents();
 
@@ -177,8 +177,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,geometry_shader4}
          * is not available, returns `0`.
-         * @requires_gl Geometry shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_GEOMETRY_INPUT_COMPONENTS}
+         * @requires_gl Geometry shaders are not available in OpenGL ES.
          */
         static Int maxGeometryInputComponents();
 
@@ -188,8 +188,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,geometry_shader4}
          * is not available, returns `0`.
-         * @requires_gl Geometry shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_GEOMETRY_OUTPUT_COMPONENTS}
+         * @requires_gl Geometry shaders are not available in OpenGL ES.
          */
         static Int maxGeometryOutputComponents();
 
@@ -199,8 +199,8 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,geometry_shader4}
          * is not available, returns `0`.
-         * @requires_gl Geometry shaders are not available in OpenGL ES.
          * @see @fn_gl{Get} with @def_gl{MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS}
+         * @requires_gl Geometry shaders are not available in OpenGL ES.
          */
         static Int maxGeometryTotalOutputComponents();
         #endif
@@ -243,7 +243,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} or
          * particular shader stage is not available, returns `0`.
-         * @requires_gl Atomic counters are not available in OpenGL ES.
          * @see @ref maxCombinedAtomicCounterBuffers(), @ref maxAtomicCounters(),
          *      @fn_gl{Get} with @def_gl{MAX_VERTEX_ATOMIC_COUNTER_BUFFERS},
          *      @def_gl{MAX_TESS_CONTROL_ATOMIC_COUNTER_BUFFERS},
@@ -251,6 +250,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_GEOMETRY_ATOMIC_COUNTER_BUFFERS},
          *      @def_gl{MAX_COMPUTE_ATOMIC_COUNTER_BUFFERS} or
          *      @def_gl{MAX_FRAGMENT_ATOMIC_COUNTER_BUFFERS}
+         * @requires_gl Atomic counters are not available in OpenGL ES.
          */
         static Int maxAtomicCounterBuffers(Type type);
 
@@ -260,9 +260,9 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} is
          * not available, returns `0`.
-         * @requires_gl Atomic counters are not available in OpenGL ES.
          * @see @ref maxAtomicCounterBuffers(), @ref maxCombinedAtomicCounters(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_ATOMIC_COUNTER_BUFFERS}
+         * @requires_gl Atomic counters are not available in OpenGL ES.
          */
         static Int maxCombinedAtomicCounterBuffers();
 
@@ -272,7 +272,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} or
          * particular shader stage is not available, returns `0`.
-         * @requires_gl Atomic counters are not available in OpenGL ES.
          * @see @ref maxCombinedAtomicCounters(), @ref maxAtomicCounterBuffers(),
          *      @fn_gl{Get} with @def_gl{MAX_VERTEX_ATOMIC_COUNTERS},
          *      @def_gl{MAX_TESS_CONTROL_ATOMIC_COUNTERS},
@@ -280,6 +279,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_GEOMETRY_ATOMIC_COUNTERS},
          *      @def_gl{MAX_COMPUTE_ATOMIC_COUNTERS} or
          *      @def_gl{MAX_FRAGMENT_ATOMIC_COUNTERS}
+         * @requires_gl Atomic counters are not available in OpenGL ES.
          */
         static Int maxAtomicCounters(Type type);
 
@@ -289,9 +289,9 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} is
          * not available, returns `0`.
-         * @requires_gl Atomic counters are not available in OpenGL ES.
          * @see @ref maxAtomicCounters(), @ref maxCombinedAtomicCounterBuffers(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_ATOMIC_COUNTERS}
+         * @requires_gl Atomic counters are not available in OpenGL ES.
          */
         static Int maxCombinedAtomicCounters();
 
@@ -301,7 +301,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_image_load_store}
          * or particular shader stage is not available, returns `0`.
-         * @requires_gl %Image load/store is not available in OpenGL ES.
          * @see @ref maxCombinedImageUniforms(),
          *      @fn_gl{Get} with @def_gl{MAX_VERTEX_IMAGE_UNIFORMS},
          *      @def_gl{MAX_TESS_CONTROL_IMAGE_UNIFORMS},
@@ -309,6 +308,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_GEOMETRY_IMAGE_UNIFORMS},
          *      @def_gl{MAX_COMPUTE_IMAGE_UNIFORMS} or
          *      @def_gl{MAX_FRAGMENT_IMAGE_UNIFORMS}
+         * @requires_gl %Image load/store is not available in OpenGL ES.
          */
         static Int maxImageUniforms(Type type);
 
@@ -318,9 +318,9 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_image_load_store}
          * is not available, returns `0`.
-         * @requires_gl %Image load/store is not available in OpenGL ES.
          * @see @ref maxImageUniforms(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_IMAGE_UNIFORMS}
+         * @requires_gl %Image load/store is not available in OpenGL ES.
          */
         static Int maxCombinedImageUniforms();
 
@@ -330,7 +330,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_storage_buffer_object}
          * or particular shader stage is not available, returns `0`.
-         * @requires_gl %Shader storage is not available in OpenGL ES.
          * @see @ref maxCombinedShaderStorageBlocks(),
          *      @fn_gl{Get} with @def_gl{MAX_VERTEX_SHADER_STORAGE_BLOCKS},
          *      @def_gl{MAX_TESS_CONTROL_SHADER_STORAGE_BLOCKS},
@@ -338,6 +337,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_GEOMETRY_SHADER_STORAGE_BLOCKS},
          *      @def_gl{MAX_COMPUTE_SHADER_STORAGE_BLOCKS} or
          *      @def_gl{MAX_FRAGMENT_SHADER_STORAGE_BLOCKS}
+         * @requires_gl %Shader storage is not available in OpenGL ES.
          */
         static Int maxShaderStorageBlocks(Type type);
 
@@ -347,9 +347,9 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,shader_storage_buffer_object}
          * is not available, returns `0`.
-         * @requires_gl %Shader storage is not available in OpenGL ES.
          * @see @ref maxShaderStorageBlocks(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_SHADER_STORAGE_BLOCKS}
+         * @requires_gl %Shader storage is not available in OpenGL ES.
          */
         static Int maxCombinedShaderStorageBlocks();
         #endif
@@ -387,7 +387,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,uniform_buffer_objects} or
          * particular shader stage is not available, returns `0`.
-         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          * @see @ref maxCombinedUniformBlocks(), @ref maxUniformComponents(),
          *      @ref maxCombinedUniformComponents(),
          *      @fn_gl{Get} with @def_gl{MAX_VERTEX_UNIFORM_BLOCKS},
@@ -396,6 +395,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_GEOMETRY_UNIFORM_BLOCKS},
          *      @def_gl{MAX_COMPUTE_UNIFORM_BLOCKS} or
          *      @def_gl{MAX_FRAGMENT_UNIFORM_BLOCKS}
+         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          */
         static Int maxUniformBlocks(Type type);
 
@@ -405,10 +405,10 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,uniform_buffer_objects} is
          * not available, returns `0`.
-         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          * @see @ref maxUniformBlocks(), @ref maxUniformComponents(),
          *      @ref maxCombinedUniformComponents(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_UNIFORM_BLOCKS}
+         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          */
         static Int maxCombinedUniformBlocks();
         #endif
@@ -420,7 +420,6 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          * The result is cached, repeated queries don't result in repeated
          * OpenGL calls. If extension @extension{ARB,uniform_buffer_objects}
          * or particular shader stage is not available, returns `0`.
-         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          * @see @ref maxUniformComponents(), @ref maxUniformBlocks(),
          *      @fn_gl{Get} with @def_gl{MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS},
          *      @def_gl{MAX_COMBINED_TESS_CONTROL_UNIFORM_COMPONENTS},
@@ -428,6 +427,7 @@ class MAGNUM_EXPORT Shader: public AbstractObject {
          *      @def_gl{MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS},
          *      @def_gl{MAX_COMBINED_COMPUTE_UNIFORM_COMPONENTS} or
          *      @def_gl{MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS}
+         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
          */
         static Int maxCombinedUniformComponents(Type type);
         #endif

src/Magnum/Texture.h

@@ -572,8 +572,6 @@ template<UnsignedInt dimensions> class Texture: public AbstractTexture {
          * or @es_extension{EXT,texture_storage} in OpenGL ES 2.0 is not
          * available, the feature is emulated with sequence of @ref setImage()
          * calls.
-         * @todo allow the user to specify ColorType explicitly to avoid
-         *      issues in WebGL (see setSubImage())
          * @see @ref maxSize(), @ref setMaxLevel(), @fn_gl{ActiveTexture},
          *      @fn_gl{BindTexture} and
          *      @fn_gl{TexStorage1D}/@fn_gl{TexStorage2D}/@fn_gl{TexStorage3D}
@@ -584,6 +582,8 @@ template<UnsignedInt dimensions> class Texture: public AbstractTexture {
          *      or @fn_gl_extension{TextureImage1D,EXT,direct_state_access}/
          *      @fn_gl_extension{TextureImage2D,EXT,direct_state_access}/
          *      @fn_gl_extension{TextureImage3D,EXT,direct_state_access}
+         * @todo allow the user to specify ColorType explicitly to avoid
+         *      issues in WebGL (see setSubImage())
          */
         Texture<dimensions>& setStorage(Int levels, TextureFormat internalFormat, const typename DimensionTraits<dimensions, Int>::VectorType& size) {
             DataHelper<dimensions>::setStorage(*this, _target, levels, internalFormat, size);
@@ -607,12 +607,12 @@ template<UnsignedInt dimensions> class Texture: public AbstractTexture {
          * and @extension{ARB,robustness} are available, the DSA version is
          * used, because it is better for performance and there isn't any
          * function combining both features.
-         * @requires_gl %Texture image queries are not available in OpenGL ES.
          * @see @fn_gl{ActiveTexture}, @fn_gl{BindTexture} and
          *      @fn_gl{GetTexLevelParameter} or @fn_gl_extension{GetTextureLevelParameter,EXT,direct_state_access}
          *      with @def_gl{TEXTURE_WIDTH}, @def_gl{TEXTURE_HEIGHT} or @def_gl{TEXTURE_DEPTH},
          *      then @fn_gl{GetTexImage}, @fn_gl_extension{GetTextureImage,EXT,direct_state_access}
          *      or @fn_gl_extension{GetnTexImage,ARB,robustness}
+         * @requires_gl %Texture image queries are not available in OpenGL ES.
          */
         void image(Int level, Image<dimensions>& image) {
             AbstractTexture::image<dimensions>(_target, level, image);

src/Magnum/TextureFormat.h

@@ -50,11 +50,11 @@ enum class TextureFormat: GLenum {
      * Red component, normalized unsigned, size implementation-dependent. Not
      * allowed in unemulated @ref Texture::setStorage() "*Texture::setStorage()"
      * calls.
-     * @deprecated_gl Prefer to use the exactly specified version of this
-     *      format, e.g. @ref Magnum::TextureFormat::R8 "TextureFormat::R8".
      * @requires_gl30 %Extension @extension{ARB,texture_rg}
      * @requires_gles30 %Extension @es_extension{EXT,texture_rg} in OpenGL ES
      *      2.0
+     * @deprecated_gl Prefer to use the exactly specified version of this
+     *      format, e.g. @ref Magnum::TextureFormat::R8 "TextureFormat::R8".
      */
     #ifndef MAGNUM_TARGET_GLES2
     Red = GL_RED,
@@ -76,11 +76,11 @@ enum class TextureFormat: GLenum {
      * Red and green component, normalized unsigned, size
      * implementation-dependent. Not allowed in unemulated
      * @ref Texture::setStorage() "*Texture::setStorage()" calls.
-     * @deprecated_gl Prefer to use the exactly specified version of this
-     *      format, e.g. @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8".
      * @requires_gl30 %Extension @extension{ARB,texture_rg}
      * @requires_gles30 %Extension @es_extension{EXT,texture_rg} in OpenGL ES
      *      2.0
+     * @deprecated_gl Prefer to use the exactly specified version of this
+     *      format, e.g. @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8".
      */
     #ifndef MAGNUM_TARGET_GLES2
     RG = GL_RG,
@@ -492,10 +492,10 @@ enum class TextureFormat: GLenum {
     /**
      * Luminance, normalized unsigned, single value used for all RGB channels.
      * Size implementation-dependent.
-     * @deprecated_gl Included for compatibility reasons only, use
-     *      @ref Magnum::TextureFormat::R8 "TextureFormat::R8" instead.
      * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
      *      @ref Magnum::TextureFormat::R8 "TextureFormat::R8" instead.
+     * @deprecated_gl Included for compatibility reasons only, use
+     *      @ref Magnum::TextureFormat::R8 "TextureFormat::R8" instead.
      */
     Luminance = GL_LUMINANCE,
 
@@ -503,10 +503,10 @@ enum class TextureFormat: GLenum {
      * Floating-point luminance and alpha channel. First value is used for all
      * RGB channels, second value is used for alpha channel. Size
      * implementation-dependent.
-     * @deprecated_gl Included for compatibility reasons only, use
-     *      @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8" instead.
      * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
      *      @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8" instead.
+     * @deprecated_gl Included for compatibility reasons only, use
+     *      @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8" instead.
      */
     LuminanceAlpha = GL_LUMINANCE_ALPHA,
     #endif
@@ -579,10 +579,10 @@ enum class TextureFormat: GLenum {
 
     /**
      * sRGB, normalized unsigned, size implementation-dependent.
-     * @todo is this allowed in core?
+     * @requires_es_extension %Extension @es_extension{EXT,sRGB}
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, i.e. @ref Magnum::TextureFormat::SRGB8 "TextureFormat::SRGB8".
-     * @requires_es_extension %Extension @es_extension{EXT,sRGB}
+     * @todo is this allowed in core?
      */
     #ifndef MAGNUM_TARGET_GLES
     SRGB = GL_SRGB,
@@ -652,10 +652,10 @@ enum class TextureFormat: GLenum {
 
     /**
      * sRGBA, normalized unsigned, size implementation-dependent.
-     * @todo is this allowed in core?
+     * @requires_es_extension %Extension @es_extension{EXT,sRGB}
      * @deprecated_gl Prefer to use the exactly specified version of this
      *      format, i.e. @ref Magnum::TextureFormat::SRGB8Alpha8 "TextureFormat::SRGB8Alpha8".
-     * @requires_es_extension %Extension @es_extension{EXT,sRGB}
+     * @todo is this allowed in core?
      */
     #ifndef MAGNUM_TARGET_GLES
     SRGBAlpha = GL_SRGB_ALPHA,
@@ -772,10 +772,10 @@ enum class TextureFormat: GLenum {
      * Depth component, size implementation-dependent. Not supported in 3D
      * textures, not allowed in unemulated @ref Texture::setStorage()
      * "*Texture::setStorage()" calls.
-     * @deprecated_gl Prefer to use the exactly specified version of this
-     *      format, e.g. @ref Magnum::TextureFormat::DepthComponent16 "TextureFormat::DepthComponent16".
      * @requires_gles30 %Extension @es_extension{OES,depth_texture} or
      *      @es_extension{ANGLE,depth_texture} in OpenGL ES 2.0
+     * @deprecated_gl Prefer to use the exactly specified version of this
+     *      format, e.g. @ref Magnum::TextureFormat::DepthComponent16 "TextureFormat::DepthComponent16".
      */
     DepthComponent = GL_DEPTH_COMPONENT,
 
@@ -835,10 +835,10 @@ enum class TextureFormat: GLenum {
      * supported in 3D textures, not allowed in unemulated
      * @ref Texture::setStorage() "*Texture::setStorage()" calls.
      * @see @ref Texture::setDepthStencilMode() "*Texture::setDepthStencilMode()"
-     * @deprecated_gl Prefer to use exactly specified version of this format,
-     *      e.g. @ref Magnum::TextureFormat::Depth24Stencil8 "TextureFormat::Depth24Stencil8".
      * @requires_gles30 %Extension @es_extension{OES,packed_depth_stencil} or
      *      @es_extension{ANGLE,depth_texture} in OpenGL ES 2.0
+     * @deprecated_gl Prefer to use exactly specified version of this format,
+     *      e.g. @ref Magnum::TextureFormat::Depth24Stencil8 "TextureFormat::Depth24Stencil8".
      */
     #ifndef MAGNUM_TARGET_GLES2
     DepthStencil = GL_DEPTH_STENCIL,