[
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
