glad-doxygen

Adds Doxygen comments above GLAD alias macros so IDE hovers work for lines like:

#define glBindBuffer glad_glBindBuffer

glad-doxygen.py does not change any of the code generated by GLAD. All it does is add comments to the code generated by GLAD.

Requirements

• Python 3.8+
• gl.xml from Khronos
• A refpage folder (e.g. OpenGL-Refpages/gl4/ with gl*.xml) — see the repo here: https://github.com/KhronosGroup/OpenGL-Refpages/tree/main
• Your GLAD header (usually glad/include/glad/gl.h) — GLAD repo: https://github.com/Dav1dde/glad

Usage

Bash:

python gen_glad_doxygen.py \
  --in       "/path/to/glad/include/glad/gl.h" \
  --xml      "/path/to/gl.xml" \
  --refpages "/path/to/OpenGL-Refpages/gl4" \
  --out      "/path/to/glad_doxygen.hpp"

PowerShell:

py .\gen_glad_doxygen.py `
      --in       "C:\path\to\glad\include\glad\gl.h" `
      --xml      "C:\path\to\gl.xml" `
      --refpages "C:\path\to\OpenGL-Refpages\gl4" `
      --out      "C:\path\to\glad_doxygen.hpp

What it writes

• \brief from the DocBook refpage (<refpurpose>) when available.
• \param names and descriptions from the refpage, with types from the matching funcprototype.
• Falls back to gl.xml for parameter types and [group: ...] / [len: ...].
• \return for non-void functions.
• \see link to the refpage.
• \note with version/extension info from gl.xml.

If a refpage covers multiple related commands, the script picks the prototype that matches the current function name.

Updated functions will end up looking like this:

GLAD_API_CALL PFNGLVIEWPORTPROC glad_glViewport;
/**
 * \brief set the viewport.
 * \param x (GLint) - Specify the lower left corner of the viewport rectangle, in pixels. The initial value is (0,0).
 * \param y (GLint) - Specify the lower left corner of the viewport rectangle, in pixels. The initial value is (0,0).
 * \param width (GLsizei) - Specify the width and height of the viewport. When a GL context is first attached to a window, width and height are set to the dimensions of that window.
 * \param height (GLsizei) - Specify the width and height of the viewport. When a GL context is first attached to a window, width and height are set to the dimensions of that window.
 * \see https://registry.khronos.org/OpenGL-Refpages/gl4/html/glViewport.xhtml
 * \note Introduced in OpenGL 1.0
 */
#define glViewport glad_glViewport