[jira] [Commented] (AVRO-2019) Improve documentation for logical type annotations in IDL

["Bridger Howell (JIRA)" <ji...@apache.org>]

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

Bridger Howell commented on AVRO-2019:
--------------------------------------

Isn't the way {{logicalType}} decorators work on types in IDL just a natural consequence of how IDL treats _any_ decorator on a type as a JSON property for that type, combined with the meaning of that field in the spec?

I think this intent is expressed clearly enough in the IDL documentation "Annotation Ordering and Namespaces" (perhaps this section title is a bit too specific):
{quote}
Java-style annotations may be used to add additional properties to types and fields throughout Avro IDL.
{quote}
(Some details on specific properties/annotations)
{quote}
Some annotations like those listed above are handled specially. All other annotations are added as properties to the protocol, message, schema or field.
{quote}

I don't think I found a great generic/shared test of this, but there are at least a few spots where the the set of tests ran by {{org.apache.avro.compiler.idl.TestIdl}} show off this kind of behavior.

For the IDL input {{simple.avdl}}, I see a case where the type of a field declared like:
{{@foo("bar") MD5 hash = "0000000000000000";}}
has the property {{"foo": "bar"}}.

> Improve documentation for logical type annotations in IDL
> ---------------------------------------------------------
>
>                 Key: AVRO-2019
>                 URL: https://issues.apache.org/jira/browse/AVRO-2019
>             Project: Avro
>          Issue Type: Improvement
>          Components: doc, logical types
>            Reporter: Andrew Rosca
>            Priority: Minor
>         Attachments: AVRO-2019.patch
>
>
> The IDL documentation lacks information for how annotations can be specified for logical types, like in the following example:
> {code}
> protocol test {
>     record test {
>         @logicalType("timestamp-millis")
>         long time;
>     }
> }
> {code}



--
This message was sent by Atlassian JIRA
(v6.4.14#64029)