Doxygen and GLSL shader

As I’ve finished the documentation-madness I stumbled over my GLSL shader. Doxygen, _the_ documentation tool of choice, reads them (as they are very c-like) but dumps them rather unfancy. Doxygen is not only very flexible – it is also extensible with filters to process other languages.


Write a small filter, that pads every shader into a class and set a namespace that acts kinda like a category (e.g. class Gauss in namespace GLSL::FILTER::BLUR). The result is my python-script.

  1. Make Doxygen aware of the filter and the newly supported file extensions. To do this, edit your Doxyfile:
    • Add FILE_PATTERNS: *.frag, *.vert
    • Add FILTER_PATTERNS: "*.frag=./", "*.vert=./"
    • Add EXTENSION_MAPPING=.frag=C++, .vert=C++ (thanks the_summer)
  2. If you want, add annotations to your shader:
    • Use @class to set the class name
    • Use @namespace to set the namespace – a category

    If you set no name, the script will use the bare filename and the default namespace is “GLSL”.

    Of course you can further document your shader with doxytags – they are fully processed by Doxygen. The only limitation here (blame my lazyness or my thought it just wasn’t worth it) is that you have to put the “class” comment (= the shader information) at the very beginning in one big blockcomment starting with /* or /**. But seriously – why would you comment it in any other way? ;-)

To better illustrate the procedure here’s a little GLSL fragment shader:

 * A simple 3x3 gaussian convolution filter, non-separated version
 * @author Sebastian Schaefer
 * @date 2012
 * @namespace GLSL::FILTER::BLUR
 * @class Gauss3x3
#version 150 core

uniform sampler2D image; ///< the input image

in vec2 tex;	///< texture coordinated
out vec4 color; ///< the color output

 * The main routine: read the 3x3 neighbours and multiply with kernel
void main()

Click here to see how the above example can look like.


Grab the filter at my github-repository
This page might get updated so please link to this page only, not the direct download. thank you!

edit: moved source to github

One thought on “Doxygen and GLSL shader

  1. the_summer

    Just a side note, because I spent a few hours searching for the solution:

    Add EXTENSION_MAPPING=.frag=C++, .vert=C++

    in case you did all of the above but the html-output does not contain your parsed shaders.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>