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.

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

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.

    Reply

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>