avro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "George Fletcher (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (AVRO-886) Support doc strings in IDL for protocols and message interfaces
Date Sat, 10 Sep 2011 15:15:08 GMT

    [ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13102060#comment-13102060

George Fletcher commented on AVRO-886:

Yes, that makes a lot of sense. Ideally, I'd like to see both options implemented. I realize
that leveraging the doc block as a way to get annotations is a work around (a.k.a. hack:)...
when I started down that path, I was hoping it was something I could do without changing the
avro code.

So it seems there are really two things to tackle...
1. Modify the IDL parser to capture doc for both the protocols and messages and save it.
2. Modify the IDL parser to allow properties for the protocol and message definitions and
then expose these properties via the parsed code. 

I'm assuming that the property information would need to appear in the JSON version of the
protocol? This then would affect all languages that depend on the JSON encoding (e.g. python).

> Support doc strings in IDL for protocols and message interfaces
> ---------------------------------------------------------------
>                 Key: AVRO-886
>                 URL: https://issues.apache.org/jira/browse/AVRO-886
>             Project: Avro
>          Issue Type: Improvement
>    Affects Versions: 1.5.2
>            Reporter: George Fletcher
> 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
> 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;
> }

This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira


View raw message