IDL43 — Need builtin annotations that can be used to document the IDL

There is a general need to document the IDL. However the IDL language does not provide any standard way to do this. As a consequence people may be forced to define custom annotations which would preclude the use across projects and/or development of general tools that are documentation aware.

To remediate this the suggestion is to add some built-in annotations that maybe used to document the IDL. For example the @documentation annotation below:

@annotation documentation {
    string value default "TBD";
};

This annotation could applied to a type declaration or to a member / element, as in:

@documentation("This documents the type Foo")
struct Foo {
    @documentation("documentation for member m1")
    long m1;
    @documentation("documentation for member m2")
    long m2;
 };

@documentation("This documents the type MyEnum")
enum MyEnum {
    @documentation("documentation for literal L1")
    L1,

    @documentation("documentation for literal L2")
    L2
 };