doc: fix GL/VK extension and version checklist to match actual workflow.

It got written once and never updated, and the order that was there
needed a lot more brain cycles than strictly necessary.

doc/developers.dox

@@ -561,14 +561,41 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
 10. Iterate until the CIs are green
 11. Merge to `master`
 
-@section developers-gl-extensions Checklist for adding / removing GL versions and extensions
+@section developers-gl-extensions Checklist for adding / removing GL extensions
-
+
-1.  Install [flextGL](https://github.com/mosra/flextgl)
+1.  Add new extensions to the GL, GLES and WebGL sections of
-2.  Go to `src/MagnumExternal/OpenGL/`:
+    `src/Magnum/GL/Extensions.h`
-    -   Update `GL/extensions.txt`, `GLES2/extensions.txt`,
+    -   Order them by extension ID that is mentioned in every extension spec
+        file. If the extension isn't in the official Khronos registry (such as
+        various ANGLE extensions), at it at the end of the range.
+    -   Update the numbering to stay monotonic and unique, round up start index
+        of next section to nearest ten to make the updates bearable
+    -   In case there's a lot of new extensions,
+        @cpp Implementation::ExtensionCount @ce might needed to be increased.
+2.  Add them alphabetically ordered to the correct list in
+    `src/magnum/GL/Context.cpp`
+    -   run GL, ES2, ES3, WebGL1 and WebGL2 build of `GLContextTest` to verify
+        everything is still okay
+    -   run GL, ES2, ES3, WebGL1 and WebGL2 build of `magnum-gl-info`
+        -   the extension should be listed unless it's not available on given
+            GL flavor
+        -   and also marked as supported unless the machine doesn't support it
+            (cross-check with `--extension-strings`)
+3.  Get [flextGL](https://github.com/mosra/flextgl) and go to
+    `src/MagnumExternal/OpenGL/`:
+    -   Add/remove extensions in `GL/extensions.txt`, `GLES2/extensions.txt`,
         `GLES2/Emscripten/extensions.txt`, `GLES3/extensions.txt`,
-        `GLES3/Emscripten/extensions.txt` (bump versions or add/remove
+        `GLES3/Emscripten/extensions.txt`, in the same order as in
-        extensions)
+        `src/Magnum/GL/Extensions.h`
+    -   For GLES and WebGL extensions, if they aren't in the official Khronos
+        registry (such as various ANGLE extensions), check if they're in
+        ANGLE's [gl_angle_ext.xml](https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml)
+        at least. If not, like with core WebGL functionality that has no match
+        in the base GLES spec, you may need to craft your own XML file. See
+        `src/MagnumExternal/OpenGL/GLES3/webgl.xml` for an example.
+    -   WebGL extensions usually have a GLES extension as a base, but then may
+        remove certains entrypoints from it. If that's the case, add it to the
+        function blacklist at the end of the Emscripten-specific files.
     -   Run `./update-flextgl.sh` to update everything. Reason there is so many
         variants of the files are the following:
         -   Desktop GLES on Windows still links to the ancient `opengl32.dll`
@@ -580,11 +607,44 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
             set the function pointers to those exported symbols in case the
             system GL header defines them.
         -   Emscripten doesn't have the ability to manually load extension
-            pointers, thus it has only header files.
+            pointers either, thus it has only header files.
-3.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
+4.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
-4.  For every new added function, add an entry to `doc/opengl-mapping.dox`
+    -   If any extensions don't add any useful symbols, comment them out in
-5.  For every new added limit query (various `GL_MIN_*` and `GL_MAX_*` macros
+        the `extensions.txt` files and regenerate to avoid needless bloat
-    etc.), add an entry to the bottom of `doc/opengl-mapping.dox`
+5.  For every new function that appeared in the regenerated extension headers,
+    add an entry to `doc/opengl-mapping.dox`
+6.  For every new added limit query that appeared in the regenerated extension
+    headers (various `GL_MIN_*` and `GL_MAX_*` macros etc.), add an entry to
+    the bottom of `doc/opengl-mapping.dox`
+7.  Add new extensions to the general GL, GLES and WebGL lists in
+    `doc/opengl-support.dox`, again matching the order in `Extensions.h` ---
+    grouped by prefix, but then ordered by extension number
+
+In order to remove GL functionality, be sure to touch all places mentioned
+above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
+unless it doesn't affect public API at all.
+
+@see @ref developers-gl-versions, @ref developers-vk-extensions
+
+@section developers-gl-versions Checklist for adding / removing GL versions
+
+1.  Add new version enum value:
+    -   to `src/Magnum/GL/Version.h`
+    -   to debug output in `src/Magnum/GL/Version.cpp`
+    -   to @cpp GL::Extension::extensions() @ce in `src/Magnum/GL/Context.cpp`
+    -   to @cpp GL::Context::tryCreate() @ce in `src/Magnum/GL/Context.cpp`
+    -   to specify GLSL version in `src/Magnum/GL/Shader.cpp`
+    -   to the list in `src/Magnum/Platform/gl-info.cpp`
+    -   to the test in `src/Magnum/GL/Test/ContextTest.cpp`
+2.  Update existing extensions with version in which they became core (last
+    parameter of the `_extension()` macro in `src/Magnum/GL/Extensions.h`)
+3.  Go to `src/MagnumExternal/OpenGL/`, bump versions in `GL/extensions.txt`,
+    `GLES2/extensions.txt`, `GLES2/Emscripten/extensions.txt`,
+    `GLES3/extensions.txt`, `GLES3/Emscripten/extensions.txt`
+4.  Continue with @ref developers-gl-extensions for all extensions that were
+    added by the new version and were not already present
+5.  For all existing extensions APIs that lose their suffix in the new version,
+    update doc references to be without the suffix
 6.  Add a table listing the new version and all new extensions in it to
     `doc/opengl-support.dox` (take a list of them from the changelog in the
     official spec PDF). Some extensions might be already present in the general
@@ -595,31 +655,13 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
 8.  Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` alias
     to `Doxyfile`, `Doxyfile-mcss` and `Doxyfile-public`, copypaste it from
     existing and change the numbers
-9.  Add new version enum value:
-    -   to `src/Magnum/GL/Version.h`
-    -   to debug output in `src/Magnum/GL/Version.cpp`
-    -   to @ref GL::Extension::extensions() in `src/Magnum/GL/Context.cpp`
-    -   to @cpp GL::Context::tryCreate() @ce in `src/Magnum/GL/Context.cpp`
-    -   to specify GLSL version in `src/Magnum/GL/Shader.cpp`
-    -   to the list in `src/Magnum/Platform/gl-info.cpp`
-    -   to the test in `src/Magnum/GL/Test/ContextTest.cpp`
-10. Add new extensions to `src/Magnum/GL/Extensions.h`
-    -   order them by extension ID that is mentioned in every extension spec
-        file
-    -   update the numbering to stay monotonic and unique, round up start index
-        of next section to nearest ten to make the updates bearable
-    -   in case there's a lot of new extensions, @cpp Implementation::ExtensionCount @ce
-        might needed to be increased
-    -   run `ContextTest` to verify everything is still okay
-11. Update existing extensions with version in which they become core (last
-    parameter of the `_extension()` macro)
-12. Update extension list in `src/magnum/GL/Context.cpp` according to changes
-    in `src/Magnum/GL/Extensions.h`
 
 In order to remove GL functionality, be sure to touch all places mentioned
 above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
 unless it doesn't affect public API at all.
 
+@see @ref developers-vk-versions
+
 @section developers-gl-functionality Checklist for adding / removing GL functionality
 
 1.  Check if given desktop functionality has equivalent in ES or WebGL, add
@@ -728,11 +770,11 @@ In order to remove OpenAL functionality, be sure to touch all places mentioned
 above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
 unless it doesn't affect public API at all.
 
-@section developers-vk-extensions Checklist for adding / removing Vulkan versions and extensions
+@section developers-vk-extensions Checklist for adding / removing Vulkan extensions
 
-1. Add new extensions to `src/Magnum/Vk/Extensions.h`
+1.  Add new extensions to `src/Magnum/Vk/Extensions.h`
     -   there's a separate list for instance and device extensions, ensure each
-        in the right list
+        is in the right list
     -   order them by extension ID that is mentioned on every extension spec
         page
     -   update the numbering to stay monotonic and unique, round up start index
@@ -743,37 +785,61 @@ unless it doesn't affect public API at all.
         need to be increased
 2.  Add them alphabetically ordered to the correct list in
     `src/Magnum/Vk/Extensions.cpp`
-3.  Update existing extensions with version in which they become core (last
+    -   run `VkExtensionsTest` to verify everything is still okay
-    parameter of the `_extension()` macro)
+    -   run `magnum-vk-info`, the extension should be listed and also marked as
-4.  Get [flextGL](https://github.com/mosra/flextgl) and go to
+        supported, unless the machine doesn't support it (cross-check with
+        `--extension-strings`)
+3.  Get [flextGL](https://github.com/mosra/flextgl) and go to
     `src/MagnumExternal/Vulkan/`:
-    -   Update `extensions.txt` (bump a version or add/remove extensions),
+    -   Add/remove extensions in `extensions.txt`, in the same order as in
-        in the same order as `Extensions.h`
+        `src/Magnum/Vk/Extensions.h`
     -   Run `./update-flexgl.sh` to update everything
-5.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
+4.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
-6.  For every new added function and structure, add an entry to
+    -   If any extensions don't add any useful symbols, comment them out in
+        the `extensions.txt` file and regenerate to avoid needless bloat
+5.  For every new added function and structure, add an entry to
     `doc/vulkan-mapping.dox`
-7.  For every new `*Feature` structure, expand the @ref Vk::DeviceFeatures
+6.  For every new `*Feature` structure, expand the @ref Vk::DeviceFeatures
     enum according to @ref developers-vk-features
-8.  Add a table listing the new version and all new extensions in it to
+7.  Add new extensions to the general list in `doc/vulkan-support.dox`, again
+    matching the order in `Extensions.h` --- grouped by prefix, but then
+    ordered by extension number
+
+In order to remove Vulkan functionality, be sure to touch all places mentioned
+above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
+unless it doesn't affect public API at all.
+
+@see @ref developers-vk-versions, @ref developers-gl-extensions
+
+@section developers-vk-versions Checklist for adding / removing Vulkan versions
+
+1.  Add new version enum value:
+    -   to `src/Magnum/Vk/Version.h`
+    -   to the list in `src/Magnum/Vk/vk-info.cpp`
+    -   to @cpp Vk::InstanceExtension::extensions() @ce and
+        @cpp Vk::Extension::extensions() @ce in `src/Magnum/Vk/Extensions.cpp`
+2.  Update existing extensions with version in which they became core (last
+    parameter of the `_extension()` macro)
+3.  Continue with @ref developers-vk-extensions for all extensions that were
+    added by the new version and were not already present
+4.  For all existing extensions APIs that lose their suffix in the new version,
+    update doc references to be without the suffix
+5.  Add a table listing the new version and all new extensions in it to
     `doc/vulkan-support.dox` (take a list of them from the changelog in the
-    official spec PDF). Some extensions might be already present in the general
+    official spec). Some extensions might be already present in the general
     extension list, move them out of there.
-9.  Add a new `requires-vkXY` page with @c \@m_footernavigation to
+6.  Add a new `requires-vkXY` page with @c \@m_footernavigation to
     `doc/vulkan-support.dox`, mention it as a @c \@subpage at a correct
     position in the list
-10. Add a new `requires-vkXY` alias to `Doxyfile`, `Doxyfile-mcss` and
+7.  Add a new `requires-vkXY` alias to `Doxyfile`, `Doxyfile-mcss` and
     `Doxyfile-public`, copypaste it from existing and change the numbers
-11. Add new version enum value:
-    -   to `src/Magnum/Vk/Version.h`
-    -   to the list in `src/Magnum/Vk/vk-info.cpp`
-    -   to @ref Vk::InstanceExtension::extensions() and
-        @ref Vk::Extension::extensions() in `src/Magnum/Vk/Extensions.cpp`
 
 In order to remove Vulkan functionality, be sure to touch all places mentioned
 above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
 unless it doesn't affect public API at all.
 
+@see @ref developers-gl-versions
+
 @section developers-vk-functionality Checklist for adding / removing Vulkan functionality
 
 @todoc adapt from the GL section

src/MagnumExternal/OpenGL/GLES2/Emscripten/extensions.txt

@@ -6,6 +6,7 @@ version 2.0 es
 
 extraspec https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml
 
+# WebGL 1 only extensions
 extension ANGLE_instanced_arrays                optional
 extension EXT_color_buffer_half_float           optional
 extension EXT_sRGB                              optional
@@ -23,6 +24,7 @@ extension OES_fbo_render_mipmap                 optional
 extension ANGLE_depth_texture                   optional
 extension EXT_draw_buffers                      optional
 
+# WebGL 1 and 2 extensions
 extension EXT_texture_filter_anisotropic        optional
 extension EXT_disjoint_timer_query              optional
 extension EXT_texture_compression_rgtc          optional
@@ -36,7 +38,7 @@ extension KHR_texture_compression_astc_ldr      optional
 
 # WEBGL_blend_equation_advanced_coherent includes just the enums but not the
 # barrier
-extension KHR_blend_equation_advanced optional
+extension KHR_blend_equation_advanced           optional
 
 # From the gl_angle_ext file, base for WEBGL_multi_draw
 extension ANGLE_multi_draw                      optional

src/MagnumExternal/OpenGL/GLES2/extensions.txt

@@ -6,6 +6,7 @@ version 2.0 es
 
 extraspec https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml
 
+# ES2-only extensions
 extension ANGLE_framebuffer_blit                optional
 extension ANGLE_framebuffer_multisample         optional
 extension ANGLE_instanced_arrays                optional