Sanitize the spec files
Yes, I am aware that the spec file will not be migrated to a comprehensive, parseable format (XML?) during the next two decades. :-)
However, it would already be a great improvement if the spec files (and thus the API) was at least designed so one has a chance of parsing it without guessing and generating somewhat more type-safe headers.
In particular, this means:
1. Agree on a consistent naming scheme, adhere to and enforce it. Please, for the sake of all that's good. The official online manpages have functions and constants prefixed with "gl" (which I deem a good thing, since that's consistent with the code you write), but the specification documents and spec files do not.
ARB approved extensions have functions and constants that are "ARB"-postfixed in their specification files to identify them as such and not GL prefixed at the same time (please, decide for one, either GL and ARB, or neither).
Except... when that's not true. ARB extensions that model functionality present in a higher core version have function names identical to the identical core functions, both in the spec files and in reality. This makes sense insofar as they are indeed the same functions as their core counterparts, however, the extension name gives no hint to this, making it unnecessarily confusing, error-prone, and hard to parse.
Most (all?) of these extensions have been amended with a comment in their "Issues" section in the mean time, but that is a poor solution. Naming these extensions differently would be less ambiguous (BRA would be a good choice to indicate that it's really a backwards-extension, or if people find the association with female underwear too repulsive, something like BACK or DOWN or COMPAT would do too... anything that gives the user a darn clue).
(all of that in principle true for non-ARB extensions as well)
2. No general (as in "GLenum in value") parameters.
Some functions have "sane" definitions, such as e.g. glDrawElements which has param mode BeginMode, which translates to [POINTS, LINES, LINE_LOOP, TRIANGLES...] as specified in enum.spec.
On the other hand, glBeginTransformFeedback, which takes a subset of these same modes (but not all of them!), accepts GLenum. Which basically means that glBeginTransformFeedback(QUAD_STRIP) is perfectly valid, and even glBeginTransformFeedback(GL_QUADS | GL_LINES) (eh..?) is valid. Or, even more nonsensical, glBeginTransformFeedback(GL_TIME_ELAPSED)or glBeginTransformFeedback(GL_VERTEX_SHADER)are entirely in accordance with the spec, and the compiler has no way of detecting and raising an error. Of course the above examples robably won't happen in this form, but it is entirely conceivable that someone accidentially feeds a harmless looking enum to the wrong function, resulting in silent failure where a compilation error could be raised.
Assuming one wanted to write a custom "gl.h/glext.h generator" that outputs more typesafe versions of the standard headers (something I'd actually do!), this is not possible at all because the relevant information is not captured in the spec file. When encountering GLenum, what else can one use but... GLenum? Without divination powers that's as good as it gets.
3. No freetext #Also: or #Also in: or #Aliases ... above or # ... already declared in comments that hold important information without also providing that information in a structured, parseable format. It is for example needlessly complicated for a parser (and a human!) to figure out what is going on when encountering comments like "# FramebufferTextureLayer already declared in ARB_framebuffer_object" or "passthru: /* OpenGL 3.0 also reuses entry points from these extensions: */" at the end of a section.
4. Did someone mention a XML spec would be good?