[
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
