Bug 353524

Description Matt Heitz 2011-08-01 16:08:37 EDT

We need something like Javadoc for EGL.  This isn't a complete proposal but it's something to get the ball rolling.

I suggest we use /** comments just like Javadoc.  Many of Javadoc's tags can be used with EGL too.  See http://en.wikipedia.org/wiki/Javadoc

There may be some open-source code for Javadoc that we can adapt for EGL.

One new tag that I've come up with is the Operation tag.  It's intended for functions which have the @Operation annotation.  When @Operation is used on a function, the parameters and return type don't have to be individually documented in the EGLDoc comments since their purposes are obvious.

The Operation tag has a "parameter" like Javadoc's Link tag.  It's the operator being implemented by the function.  Here is an example.

/**
 * {@Operation +} Adds two numbers.
 */
static function $Plus(lvalue EglInt in, rvalue EglInt in) returns (EglInt) {@Operation{"+"}};