Author: cutting
Date: Thu Mar 31 22:25:29 2011
New Revision: 1087465
URL: http://svn.apache.org/viewvc?rev=1087465&view=rev
Log:
Merge -c 1087463 from trunk to 1.5 branch. Fixes: AVRO-296.
Modified:
avro/branches/branch-1.5/ (props changed)
avro/branches/branch-1.5/CHANGES.txt
avro/branches/branch-1.5/doc/src/content/xdocs/idl.xml
avro/branches/branch-1.5/lang/java/avro/src/main/java/org/apache/avro/Schema.java
avro/branches/branch-1.5/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
avro/branches/branch-1.5/lang/java/compiler/src/test/idl/input/simple.avdl
avro/branches/branch-1.5/lang/java/compiler/src/test/idl/output/simple.avpr
Propchange: avro/branches/branch-1.5/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Mar 31 22:25:29 2011
@@ -1 +1 @@
-/avro/trunk:1075938,1075993,1078917,1079055,1079060,1079063,1083246,1085921,1086727,1086730,1086866,1087076,1087129,1087136,1087439-1087440
+/avro/trunk:1075938,1075993,1078917,1079055,1079060,1079063,1083246,1085921,1086727,1086730,1086866,1087076,1087129,1087136,1087439-1087440,1087463
Modified: avro/branches/branch-1.5/CHANGES.txt
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/CHANGES.txt?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
--- avro/branches/branch-1.5/CHANGES.txt (original)
+++ avro/branches/branch-1.5/CHANGES.txt Thu Mar 31 22:25:29 2011
@@ -20,6 +20,9 @@ Avro 1.5.1 (unreleased)
AVRO-787. Ruby: Make compatible with Ruby 1.9. (Michael L. Artz via
cutting)
+ AVRO-296. IDL: Use double-asterisk comments for schema documentation.
+ (cutting)
+
BUG FIXES
AVRO-786. Java: Fix equals() to work on objects containing maps. (cutting)
Modified: avro/branches/branch-1.5/doc/src/content/xdocs/idl.xml
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/doc/src/content/xdocs/idl.xml?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
--- avro/branches/branch-1.5/doc/src/content/xdocs/idl.xml (original)
+++ avro/branches/branch-1.5/doc/src/content/xdocs/idl.xml Thu Mar 31 22:25:29
2011
@@ -302,6 +302,9 @@ void fireAndForget(string message) onewa
<p>All Java-style comments are supported within a Avro IDL file. Any
text following
<code>//</code> on a line is ignored, as is any text between
<code>/*</code> and
<code>*/</code>, possibly spanning multiple lines.</p>
+ <p>Comments that begin with <code>/**</code> are used as the
+ documentation string for the type or field definition that
+ follows the comment.</p>
</section>
<section id="minutiae_escaping">
<title>Escaping Identifiers</title>
Modified:
avro/branches/branch-1.5/lang/java/avro/src/main/java/org/apache/avro/Schema.java
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/lang/java/avro/src/main/java/org/apache/avro/Schema.java?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
---
avro/branches/branch-1.5/lang/java/avro/src/main/java/org/apache/avro/Schema.java
(original)
+++
avro/branches/branch-1.5/lang/java/avro/src/main/java/org/apache/avro/Schema.java
Thu Mar 31 22:25:29 2011
@@ -618,6 +618,8 @@ public abstract class Schema {
gen.writeStringField("type", isError?"error":"record");
writeName(names, gen);
names.space = name.space; // set default namespace
+ if (getDoc() != null)
+ gen.writeStringField("doc", getDoc());
gen.writeFieldName("fields");
fieldsToJson(names, gen);
props.write(gen);
@@ -686,6 +688,8 @@ public abstract class Schema {
gen.writeStartObject();
gen.writeStringField("type", "enum");
writeName(names, gen);
+ if (getDoc() != null)
+ gen.writeStringField("doc", getDoc());
gen.writeArrayFieldStart("symbols");
for (String symbol : symbols)
gen.writeString(symbol);
@@ -825,6 +829,8 @@ public abstract class Schema {
gen.writeStartObject();
gen.writeStringField("type", "fixed");
writeName(names, gen);
+ if (getDoc() != null)
+ gen.writeStringField("doc", getDoc());
gen.writeNumberField("size", size);
props.write(gen);
aliasesToJson(gen);
Modified:
avro/branches/branch-1.5/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
---
avro/branches/branch-1.5/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
(original)
+++
avro/branches/branch-1.5/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
Thu Mar 31 22:25:29 2011
@@ -91,6 +91,14 @@ public class Idl
String namespace;
Map<String,Schema> names = new LinkedHashMap<String,Schema>();
+ private static final ThreadLocal<String> DOC = new ThreadLocal<String>();
+ static void setDoc(String doc) { DOC.set(doc.trim()); }
+ static String getDoc() {
+ String doc = DOC.get();
+ DOC.set(null);
+ return doc;
+ }
+
public Idl(File inputFile) throws IOException {
this(new FileInputStream(inputFile), "UTF-8");
this.inputDir = inputFile.getParentFile();
@@ -140,34 +148,34 @@ SKIP :
/* COMMENTS */
-MORE :
+SKIP :
{
- <"/**" ~["/"]> { input_stream.backup(1); } : IN_FORMAL_COMMENT
-|
- "/*" : IN_MULTI_LINE_COMMENT
+ <SINGLE_LINE_COMMENT: "//" (~["\n", "\r"])* ("\n" | "\r" | "\r\n")?>
}
-SPECIAL_TOKEN :
+SKIP :
{
- <SINGLE_LINE_COMMENT: "//" (~["\n", "\r"])* ("\n" | "\r" | "\r\n")?>
+ <"/**" ~["/"]> { input_stream.backup(1); } : DOC_COMMENT
+|
+ "/*" : MULTI_LINE_COMMENT
}
-<IN_FORMAL_COMMENT>
-SPECIAL_TOKEN :
+<DOC_COMMENT,MULTI_LINE_COMMENT>
+MORE :
{
- <FORMAL_COMMENT: "*/" > : DEFAULT
+ < ~[] >
}
-<IN_MULTI_LINE_COMMENT>
+<DOC_COMMENT>
SPECIAL_TOKEN :
{
- <MULTI_LINE_COMMENT: "*/" > : DEFAULT
+ <"*/" > {Idl.setDoc(image.substring(0, image.length()-2));} : DEFAULT
}
-<IN_FORMAL_COMMENT,IN_MULTI_LINE_COMMENT>
-MORE :
+<MULTI_LINE_COMMENT>
+SKIP :
{
- < ~[] >
+ <"*/" > : DEFAULT
}
/* RESERVED WORDS AND LITERALS */
@@ -1038,6 +1046,7 @@ Protocol ProtocolDeclaration():
"protocol"
name = Identifier()
{
+ getDoc(); // consume doc
p = new Protocol(name, namespace);
}
ProtocolBody(p)
@@ -1057,7 +1066,7 @@ Schema EnumDeclaration():
name = Identifier()
symbols = EnumBody()
{
- Schema s = Schema.createEnum(name, null, this.namespace, symbols);
+ Schema s = Schema.createEnum(name, getDoc(), this.namespace, symbols);
names.put(s.getFullName(), s);
return s;
}
@@ -1169,7 +1178,7 @@ Schema FixedDeclaration():
"fixed" name = Identifier() "(" sizeTok = <INTEGER_LITERAL> ")"
";"
{
- Schema s = Schema.createFixed(name, null, this.namespace,
+ Schema s = Schema.createFixed(name, getDoc(), this.namespace,
Integer.parseInt(sizeTok.image));
names.put(s.getFullName(), s);
return s;
@@ -1190,7 +1199,7 @@ Schema RecordDeclaration():
name = Identifier()
{
Schema result = Schema.createRecord(
- name, null, this.namespace, isError);
+ name, getDoc(), this.namespace, isError);
names.put(result.getFullName(), result);
}
"{"
@@ -1254,7 +1263,7 @@ void VariableDeclarator(Schema type, Lis
for (String key : props.keySet())
if ("order".equals(key))
order =
Field.Order.valueOf(getTextProp(key,props,token).toUpperCase());
- Field field = new Field(name, type, null, defaultValue, order);
+ Field field = new Field(name, type, getDoc(), defaultValue, order);
for (String key : props.keySet())
if ("order".equals(key)) { // already handled: ignore
} else if ("aliases".equals(key)) { // aliases
Modified:
avro/branches/branch-1.5/lang/java/compiler/src/test/idl/input/simple.avdl
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/lang/java/compiler/src/test/idl/input/simple.avdl?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
--- avro/branches/branch-1.5/lang/java/compiler/src/test/idl/input/simple.avdl
(original)
+++ avro/branches/branch-1.5/lang/java/compiler/src/test/idl/input/simple.avdl
Thu Mar 31 22:25:29 2011
@@ -21,6 +21,7 @@
*/
@namespace("org.apache.avro.test")
protocol Simple {
+ /** A kind of record. */
@aliases(["org.foo.KindOf"])
enum Kind {
FOO,
@@ -28,11 +29,14 @@ protocol Simple {
BAZ
}
+ /** An MD5 hash. */
fixed MD5(16);
+ /** A TestRecord. */
record TestRecord {
string @order("ignore") name = "foo";
+ /** The kind of record. */
Kind @order("descending") kind;
@foo("bar") MD5 hash;
Modified:
avro/branches/branch-1.5/lang/java/compiler/src/test/idl/output/simple.avpr
URL:
http://svn.apache.org/viewvc/avro/branches/branch-1.5/lang/java/compiler/src/test/idl/output/simple.avpr?rev=1087465&r1=1087464&r2=1087465&view=diff
==============================================================================
--- avro/branches/branch-1.5/lang/java/compiler/src/test/idl/output/simple.avpr
(original)
+++ avro/branches/branch-1.5/lang/java/compiler/src/test/idl/output/simple.avpr
Thu Mar 31 22:25:29 2011
@@ -4,16 +4,19 @@
"types" : [ {
"type" : "enum",
"name" : "Kind",
+ "doc" : "A kind of record.",
"symbols" : [ "FOO", "BAR", "BAZ" ],
"aliases" : [ "org.foo.KindOf" ]
}, {
"type" : "fixed",
"name" : "MD5",
+ "doc" : "An MD5 hash.",
"size" : 16,
"foo" : "bar"
}, {
"type" : "record",
"name" : "TestRecord",
+ "doc" : "A TestRecord.",
"fields" : [ {
"name" : "name",
"type" : "string",
@@ -22,6 +25,7 @@
}, {
"name" : "kind",
"type" : "Kind",
+ "doc" : "The kind of record.",
"order" : "descending"
}, {
"name" : "hash",
