Uploaded image for project: 'Avro'
  1. Avro
  2. AVRO-886

Support doc strings in IDL for protocols and message interfaces

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 1.6.0
    • Fix Version/s: 1.6.0
    • Component/s: java
    • Labels:
      None
    • Hadoop Flags:
      Reviewed
    • Release Note:
      IDL parsing updated to support capturing doc strings for both Protocol and Message entities.
    • Tags:
      IDL, Code generation

      Description

      I would like to be able to add documentation to the IDL that will get parsed with more types than Enum, Fixed and Record. Specifically, I'd like to support doc strings for protocols and message interfaces. One purpose is to be able to write the documentation into the generated code.

      The specific use case is to use information in the documentation strings to auto generate java annotations in the generated Java code. This is done with our own specifics compiler.

      Here is an example 'marked up' IDL file...

      /** class=@AccessControl(group="normal") */
      @namespace("com.aol.interfaces.echo")
      protocol EchoService {

      import idl "Errors.avdl";

      /** Message structure for the echo service */
      record Message

      { /** the string to be echo'd */ string echome; map<string> echoes; }

      /** method=@AccessControl(source="MyService") */
      string echoString(string msg) throws com.aol.interfaces.error.ServiceError;
      Message echoMessage(Message msg) throws com.aol.interfaces.error.ServiceError;

      void publishMessage(string msg) oneway;
      }

        Attachments

        1. avro-doc-v2.patch
          19 kB
          George Fletcher
        2. newline-in-doc-test.patch
          1 kB
          Doug Cutting
        3. avroTrace-bug.patch
          0.6 kB
          George Fletcher
        4. idl-escapes.patch
          1 kB
          Doug Cutting
        5. avro-doc-v3.patch
          14 kB
          George Fletcher
        6. AVRO-866.patch
          14 kB
          Doug Cutting

          Activity

            People

            • Assignee:
              gffletch George Fletcher
              Reporter:
              gffletch George Fletcher
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: