avro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cutt...@apache.org
Subject svn commit: r1087465 - in /avro/branches/branch-1.5: ./ doc/src/content/xdocs/ lang/java/avro/src/main/java/org/apache/avro/ lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/ lang/java/compiler/src/test/idl/input/ lang/java/compiler/src/...
Date Thu, 31 Mar 2011 22:25:29 GMT
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",



Mime
View raw message