[
https://issues.apache.org/jira/browse/AVRO-1329?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17107156#comment-17107156
]
Martin Jubelgas commented on AVRO-1329:
---------------------------------------
I think it's without question here that the order of symbols is, and will have
to be in accordance to the definition in the symbols field of an enum, and
keeping that field around is, despite its limitations, without alternative.
So, the options to encode other information like per-symbol doc, per-symbol
aliases, and (maybe) per-symbol-properties (i.e. annotations) are basically
like:
1.) Based loosely on original suggestion by Doug Cutting:
{code:json}
{
"name" : "Foo",
"type" : "enum",
"doc" : "enum global doc",
"symbols" : [ "zero", "one", "many" ],
"symbols-doc" : [ "", "", "more than one" ],
"symbols-alias" : [ [], [], [ "two" ] ],
"symbols-attributes" : [ {}, { "numerus" : "singular" }, {} ]
}{code}
2.) Using a new definition AND an old definition:
{code:json}
{
"name" : "Foo",
"type" : "enum",
"doc" : "enum global doc",
"symbols" : [ "zero", "one", "many" ],
"symbols-def" : [
{
"name" : "zero"
},
{
"name" : "one",
"numerus" : "singular"
},
{
"name" : "many",
"doc" : "more than one",
"aliases" : [ "two" ]
}
]
}
{code}
3. Using an (optional) parallel array for all information besides the name
{code:json}
"name" : "Foo",
"type" : "enum",
"doc" : "enum global doc",
"symbols" : [ "zero", "one", "many" ],
"symbols-def" : [
{},
{
"numerus" : "singular"
},
{
"doc" : "more than one",
"aliases" : [ "two" ]
}
]
}
{code}
4. Using an (optional) map for all information besides the name
{code:json}
"name" : "Foo",
"type" : "enum",
"doc" : "enum global doc",
"symbols" : [ "zero", "one", "many" ],
"symbols-def" : {
"one" : {
"numerus" : "singular"
},
"many" : {
"doc" : "more than one",
"aliases" : [ "two" ]
}
]
}
{code}
Personally, I disfavour number 1, because it doesn't feel "right" to me. As for
the other four, I am very open, and since it would be an extension of the spec,
there should really be as much concensus as possible on this. The issue
addressed by it is one that's nearly as old as avro is itself, and its
technically easy enough to tackle. So please let's get that on the road, I
don't want to have people resort to their custom implementations of codegen and
the like to get this working.
So, I want to raise my hand for options 2, 3 or 4.
> Get per-symbol doc for enums
> ----------------------------
>
> Key: AVRO-1329
> URL: https://issues.apache.org/jira/browse/AVRO-1329
> Project: Apache Avro
> Issue Type: Improvement
> Components: doc
> Affects Versions: 1.7.4
> Reporter: Felix GV
> Priority: Minor
>
> It would be nice to have the ability to add documentation for each symbol of
> an enum.
> Doug Cutting, quoted from the mailing list:
> Documentation per enum symbol is not currently supported, but would not be
> difficult to add. Please file an issue in Jira if you'd like to see this. For
> compatibility, in Json, this would probably appear as a parallel array of
> documentation strings, e.g., something like:
> ("name": "Foo", "type":"enum", "doc":"an enum", "symbols":["X","Y"],
> "symbols-doc":["X is X", "Y is Y"]}
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
