IDL 4.3 RTF Avatar
  1. OMG Issue

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

  • Key: IDL43-33
  • Status: open  
  • Source: Real-Time Innovations ( Gerardo Pardo-Castellote)
  • Summary:

    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
     };
    
  • Reported: IDL 4.2 — Thu, 11 Apr 2019 18:17 GMT
  • Updated: Fri, 12 Apr 2019 23:26 GMT