You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avro.apache.org by "George Fletcher (JIRA)" <ji...@apache.org> on 2011/09/08 19:08:08 UTC
[jira] [Created] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Status: Open (was: Patch Available)
Did not attache the patch :(
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13106554#comment-13106554 ]
George Fletcher commented on AVRO-886:
--------------------------------------
Ok, new patch file (avro-doc-v3.patch) uploaded.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc-v3.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Doug Cutting updated AVRO-886:
------------------------------
Resolution: Fixed
Assignee: George Fletcher
Hadoop Flags: [Reviewed]
Status: Resolved (was: Patch Available)
I committed this. Thanks, George!
> 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.6.0
> Reporter: George Fletcher
> Assignee: George Fletcher
> Fix For: 1.6.0
>
> Attachments: AVRO-866.patch, avro-doc-v2.patch, avro-doc-v3.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13105076#comment-13105076 ]
George Fletcher commented on AVRO-886:
--------------------------------------
For good measure, if you make the comment of the Span record in the avroTrace.avdl file look like this
{noformat}
/**
* An individual span is the basic unit of testing.
* The record is used by both \"client\" and \"server\".
*/
record Span {
{noformat}
you will trigger the other bug I ran into while adding doc support for Protocols and Messages. Bascially, the SpecificCompiler.java in it's javaEscape() method doesn't ignore already escaped double-quotes and hence replaces {noformat}\" with \\"{noformat} which causes an improperly escaped string in the generated java sources. In the case the code doesn't even compile. The resulting generated avroTrace.java file contains this statement.
{noformat}
public static final org.apache.avro.Protocol PROTOCOL = org.apache.avro.Protocol.parse("{\"protocol\":\"AvroTrace\",\"namespace\":\"org.apache.avro.ipc.trace\",\"types\":[{\"type\":\"enum\",\"name\":\"SpanEvent\",\"symbols\":[\"SERVER_RECV\",\"SERVER_SEND\",\"CLIENT_RECV\",\"CLIENT_SEND\"]},{\"type\":\"fixed\",\"name\":\"ID\",\"size\":8},{\"type\":\"record\",\"name\":\"TimestampedEvent\",\"fields\":[{\"name\":\"timeStamp\",\"type\":\"long\"},{\"name\":\"event\",\"type\":[\"SpanEvent\",\"string\"]}]},{\"type\":\"record\",\"name\":\"Span\",\"doc\":\"* An individual span is the basic unit of testing.\n * The record is used by both \\\\"client\\\\" and \\\\"server\\\\".\",\"fields\":[{\"name\":\"traceID\",\"type\":\"ID\"},{\"name\":\"spanID\",\"type\":\"ID\"},{\"name\":\"parentSpanID\",\"type\":[\"ID\",\"null\"]},{\"name\":\"messageName\",\"type\":\"string\"},{\"name\":\"requestPayloadSize\",\"type\":\"long\"},{\"name\":\"responsePayloadSize\",\"type\":\"long\"},{\"name\":\"requestorHostname\",\"type\":[\"string\",\"null\"]},{\"name\":\"responderHostname\",\"type\":[\"string\",\"null\"]},{\"name\":\"events\",\"type\":{\"type\":\"array\",\"items\":\"TimestampedEvent\"}},{\"name\":\"complete\",\"type\":\"boolean\"}]}],\"messages\":{\"getAllSpans\":{\"request\":[],\"response\":{\"type\":\"array\",\"items\":\"Span\"}},\"getSpansInRange\":{\"request\":[{\"name\":\"start\",\"type\":\"long\"},{\"name\":\"end\",\"type\":\"long\"}],\"response\":{\"type\":\"array\",\"items\":\"Span\"}}}}");
{noformat}
Scroll until you find the "doc" string for the "Span" record. I used a fresh checkout of 1.6.0 for this test that did NOT contain my patch.
I'm sorry that my initial comments weren't very clear.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch, avroTrace-bug.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: avroTrace-bug.patch
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch, avroTrace-bug.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: avro-doc-v3.patch
This time with ASF license grant
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc-v3.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Doug Cutting updated AVRO-886:
------------------------------
Attachment: idl-escapes.patch
George: you're right, there's a bug in the escaping of schemas included in specific compiler output. I've attached a one-line change that fixes this. With this, I don't believe you'll need to make all the escape-related changes in your patch.
Should I file a separate issue for this, or would you just like to include this change in your patch?
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: avro-doc-v2.patch
Minor update to the patch that restores newlines in the multi-line doc strings when written by the velocity templates.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: avro-doc.patch
Patch to avro 1.6.0 that improves the IDL parser to capture doc strings for both protocols and messages.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13102351#comment-13102351 ]
Doug Cutting commented on AVRO-886:
-----------------------------------
The JSON is meant to be extensible:
"Attributes not defined in this document are permitted as metadata, but must not affect the format of serialized data."
from http://avro.apache.org/docs/current/spec.html#schemas
So no changes are required to other implementations if we start using a "java-annotations" property.
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13104795#comment-13104795 ]
George Fletcher commented on AVRO-886:
--------------------------------------
Not sure how to delete attached files, so if interested in the patch, please use avro-doc-v2.patch to pick up all the latest tweaks. Thanks.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13104739#comment-13104739 ]
George Fletcher commented on AVRO-886:
--------------------------------------
So I believe I've got code working against 1.6.0-SNAPSHOT (revision 1170735) to handle doc strings for protocol and message entities. I'll submit a patch.
I ran into a couple interesting issues that are probably undiscovered bugs in the existing implementations.
1. The SpecificCompiler.java javaEscape() method is currently escaping double-quotes even if they are already escaped in the string. I changed the replace() call with replaceAll("([^\\\\])\"", "$1\\\\\"").replaceFirst("^\"", "\\\\\"") which basically will replace a double-quote with \" as long as it is not already escaped.
2. JSON doc strings need newlines to be escaped. If a doc string was multi-line and contained newlines, the JSON parser complained. I fixed these by escaping the newlines when ever generated the JSON objects (e.g. toJson()).
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Status: Patch Available (was: Open)
Attached file avro-doc.patch to this jira ticket
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ 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). Correct?
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Doug Cutting updated AVRO-886:
------------------------------
Attachment: AVRO-866.patch
This is looking great. A few nits:
- The changes to output/unicode.avpr were garbled.
- There were some whitespace/indendation changes in Protocol.java that weren't needed.
I've attached a new version of a patch that fixes these details. I'll commit this tomorrow unless there are objections.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: AVRO-866.patch, avro-doc-v2.patch, avro-doc-v3.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: avro-doc-v3.patch
Simplified JSON string escaping logic (thanks Doug!)
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc-v3.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: (was: avro-doc.patch)
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avroTrace-bug.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Attachment: (was: avro-doc-v3.patch)
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13105070#comment-13105070 ]
George Fletcher commented on AVRO-886:
--------------------------------------
Right and that is the problem I ran into with multi-line comments in the IDL. In the patch you provided, the newline (\n) is escaped as in \\n. As long as the JSON string has the newlines escaped everything is fine. The problem that I found is that the IDL parsing logic does NOT escape the newlines in a multi-line comment. This is true for enum, fixed and record schemas.
The code generation phased worked fine, but when it came time to compile the generated java code, the Protocol.parse() method failed because the "doc" string in the JSON structure did not have the newlines properly escaped.
For example, try adding the following multi-line comment to the avroTrace.avdl file.
/**
* An individual span is the basic unit of testing.
* The record is used by both client and server.
*/
record Span {
The some of the tests in the ipc module will fail because the doc string contains an un-escaped newline. I've uploaded the simple patch for the avroTrace.avdl file.
Hence in my patch, I explicitly escape any newlines in the doc strings when generating the JSON format, and convert them back to newlines when "getting" the doc (protocol.getDoc()) so that comments in the generated code look much better.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Doug Cutting updated AVRO-886:
------------------------------
Attachment: newline-in-doc-test.patch
> JSON doc strings need newlines to be escaped.
Jackson does not usually emit JSON it cannot parse. Here's a patch that adds a test of parsing newlines in a doc string. The modified test passes for me. Where are you seeing failures?
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13105071#comment-13105071 ]
George Fletcher commented on AVRO-886:
--------------------------------------
Argh... looks like I need wiki help:) The first sentence of my last comment should read...
Right and that is the problem I ran into with multi-line comments in the IDL. In the patch you provided, the newline (\n) is escaped as in {noformat}\\n{noformat}
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avro-doc.patch, avroTrace-bug.patch, newline-in-doc-test.patch
>
>
> 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
[jira] [Updated] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Fletcher updated AVRO-886:
---------------------------------
Fix Version/s: 1.6.0
Affects Version/s: (was: 1.5.2)
1.6.0
Release Note: IDL parsing updated to support capturing doc strings for both Protocol and Message entities.
Status: Patch Available (was: Open)
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
>
> 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
[jira] [Commented] (AVRO-886) Support doc strings in IDL for
protocols and message interfaces
Posted by "George Fletcher (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/AVRO-886?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13106495#comment-13106495 ]
George Fletcher commented on AVRO-886:
--------------------------------------
I'm happy to update my patch to include this simplification.
> 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.6.0
> Reporter: George Fletcher
> Fix For: 1.6.0
>
> Attachments: avro-doc-v2.patch, avroTrace-bug.patch, idl-escapes.patch, newline-in-doc-test.patch
>
>
> 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