[jira] [Commented] (AVRO-886) Support doc strings in IDL for protocols and message interfaces

["Doug Cutting (JIRA)" <ji...@apache.org>]

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

Doug Cutting commented on AVRO-886:
-----------------------------------

I think getting protocol and message documentation into javadoc would be a good thing.

That said, if generating protocol annotations is the desired end-goal, then it does not seem appropriate to use documentation strings.  Rather, I'd suggest that protocols and messages in Java be extended to support arbitrary properties (like schemas and fields already do).  Then the IDL parser would need to be changed to parse these (as it already does for schemas and fields).  Finally, we could alter the templates to emit annotations from the value of the "java-annotations" property of protocols, messages, schemas and fields.  Does that make sense?

> 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 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;
> }

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