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.

Idea

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 glslfilter.py python-script.

Usage

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=./glslfilter.py", "*.vert=./glslfilter.py"
   • 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:

Example

/**
 * 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.

Download

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

—
edit: moved source to github