You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@avro.apache.org by George Fletcher <gf...@aol.com> on 2011/09/01 19:34:40 UTC
Doc strings in IDL not working
Hi,
I'm trying to use the velocity templates to extract doc strings from the
IDL using my own SpecificCompiler. The IDL file looks like this...
/** 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;
}
I expected based on AVRO-296
(https://issues.apache.org/jira/browse/AVRO-296) being part of 1.5.1
that I should be able to get the doc strings from the parsed IDL.
However, this doesn't appear to be working. In looking at the source
code, it appears that doc strings are only saved for Enum, Fixed and Schema.
Given that doc strings are supported for Schemas, I expected to see the
'Message structure for the echo service' in my generated java code.
However, even with the default velocity templates this string isn't
present in the generated files.
Has any else run into this? Do I just have some simple syntax error in
my IDL? Is there are reason that the parser doesn't support doc strings
for more of the types? (e.g. Messages?)
Thanks,
George
Re: Doc strings in IDL not working
Posted by George Fletcher <gf...@aol.com>.
Comments inline.
On 9/2/11 8:29 PM, Scott Carey wrote:
> On 9/1/11 10:34 AM, "George Fletcher" <gffletch@aol.com
> <ma...@aol.com>> wrote:
>
> Hi,
>
> I'm trying to use the velocity templates to extract doc strings
> from the IDL using my own SpecificCompiler. The IDL file looks
> like this...
>
> /** 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;
> }
>
> I expected based on AVRO-296
> (https://issues.apache.org/jira/browse/AVRO-296) being part of
> 1.5.1 that I should be able to get the doc strings from the parsed
> IDL. However, this doesn't appear to be working. In looking at the
> source code, it appears that doc strings are only saved for Enum,
> Fixed and Schema.
>
>
> According to the Avro Specification, only Enum, Fixed, and Record are
> named types that can have a 'doc' field in the Schema.
> http://avro.apache.org/docs/1.5.3/spec.html#schema_record
>
> Can you open a ticket to discuss adding doc support for other schema
> types, and list out some use cases? Supporting doc for all types has
> some implementation complexities, which is why it is currently only
> valid on named types. For unnamed types, it is arguably a bug that
> you can set a property named 'doc' in the schema for unnamed types,
> but the spec is not clear.
Sure. Here is the ticket I opened:
https://issues.apache.org/jira/browse/AVRO-886
>
>
>
> Given that doc strings are supported for Schemas, I expected to
> see the 'Message structure for the echo service' in my generated
> java code. However, even with the default velocity templates this
> string isn't present in the generated files.
>
>
> Supporting a use case where documentation from IDL -> Java code
> persists is different than supporting 'doc' fields in the schema in
> general for all types. Is this the most important use case?
The core use case is being able to add environment specific flags in the
documentation section that can be used by the code generation software
to enhance the generated code. In this particular case, add annotations
to the generated java code.
Thanks,
George
--
Chief Architect AIM: gffletch
Identity Services Engineering Work: george.fletcher@teamaol.com
AOL Inc. Home: gffletch@aol.com
Mobile: +1-703-462-3494 Blog: http://practicalid.blogspot.com
Office: +1-703-265-2544 Twitter: http://twitter.com/gffletch
Re: Doc strings in IDL not working
Posted by Scott Carey <sc...@apache.org>.
On 9/1/11 10:34 AM, "George Fletcher" <gf...@aol.com> wrote:
>
> Hi,
>
> I'm trying to use the velocity templates to extract doc strings from the IDL
> using my own SpecificCompiler. The IDL file looks like this...
>
> /** 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;
> }
>
> I expected based on AVRO-296 (https://issues.apache.org/jira/browse/AVRO-296)
> being part of 1.5.1 that I should be able to get the doc strings from the
> parsed IDL. However, this doesn't appear to be working. In looking at the
> source code, it appears that doc strings are only saved for Enum, Fixed and
> Schema.
According to the Avro Specification, only Enum, Fixed, and Record are named
types that can have a 'doc' field in the Schema.
http://avro.apache.org/docs/1.5.3/spec.html#schema_record
Can you open a ticket to discuss adding doc support for other schema types,
and list out some use cases? Supporting doc for all types has some
implementation complexities, which is why it is currently only valid on
named types. For unnamed types, it is arguably a bug that you can set a
property named 'doc' in the schema for unnamed types, but the spec is not
clear.
>
>
> Given that doc strings are supported for Schemas, I expected to see the
> 'Message structure for the echo service' in my generated java code. However,
> even with the default velocity templates this string isn't present in the
> generated files.
Supporting a use case where documentation from IDL -> Java code persists is
different than supporting 'doc' fields in the schema in general for all
types. Is this the most important use case?
>
> Has any else run into this? Do I just have some simple syntax error in my
> IDL? Is there are reason that the parser doesn't support doc strings for more
> of the types? (e.g. Messages?)
>
> Thanks,
> George
>
>