AVRO-1619. Java: Improve javadoc comments in generated code. Contribu…

…ted by Niels Basjes. git-svn-id: https://svn.apache.org/repos/asf/avro/trunk@1645771 13f79535-47bb-0310-9956-ffa450edef68
samschlegel · Dec 15, 2014 · 71c29bd · 71c29bd
1 parent 6501dd5
commit 71c29bd
Show file tree

Hide file tree

Showing 5 changed files with 176 additions and 68 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -47,6 +47,9 @@ Trunk (not yet released)
 
     AVRO-1585. Java: Deprecate Jackson classes in public API. (tomwhite)
 
+    AVRO-1619. Java: Improve javadoc comments in generated code.
+    (Niels Basjes via cutting)
+
   BUG FIXES
 
     AVRO-1553. Java: MapReduce never uses MapOutputValueSchema (tomwhite)

diff --git a/...iler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm b/...iler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm
@@ -106,7 +106,8 @@ public class ${this.mangle($schema.getName())}#if ($schema.isError()) extends or
 #foreach ($field in $schema.getFields())
   /**
    * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field.
-#if ($field.doc())   * $field.doc()#end
+#if ($field.doc())   * $field.doc()
+#end
    */
   public ${this.javaType($field.schema())} ${this.generateGetMethod($schema, $field)}() {
     return ${this.mangle($field.name(), $schema.isError())};
@@ -115,7 +116,8 @@ public class ${this.mangle($schema.getName())}#if ($schema.isError()) extends or
 #if ($this.createSetters)
   /**
    * Sets the value of the '${this.mangle($field.name(), $schema.isError())}' field.
-#if ($field.doc())   * $field.doc()#end
+#if ($field.doc())   * $field.doc()
+#end
    * @param value the value to set.
    */
   public void ${this.generateSetMethod($schema, $field)}(${this.javaType($field.schema())} value) {
@@ -205,25 +207,42 @@ public class ${this.mangle($schema.getName())}#if ($schema.isError()) extends or
 #end
 
 #foreach ($field in $schema.getFields())
-    /** Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field */
+    /**
+      * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field.
+#if ($field.doc())      * $field.doc()
+#end
+      */
     public ${this.javaType($field.schema())} ${this.generateGetMethod($schema, $field)}() {
       return ${this.mangle($field.name(), $schema.isError())};
     }
-
-    /** Sets the value of the '${this.mangle($field.name(), $schema.isError())}' field */
+
+    /**
+      * Sets the value of the '${this.mangle($field.name(), $schema.isError())}' field.
+#if ($field.doc())      * $field.doc()
+#end
+      * @param value the value to set.
+      */
     public #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder ${this.generateSetMethod($schema, $field)}(${this.javaUnbox($field.schema())} value) {
       validate(fields()[$field.pos()], value);
       this.${this.mangle($field.name(), $schema.isError())} = value;
       fieldSetFlags()[$field.pos()] = true;
       return this; 
     }
-
-    /** Checks whether the '${this.mangle($field.name(), $schema.isError())}' field has been set */
+
+    /** 
+      * Checks whether the '${this.mangle($field.name(), $schema.isError())}' field has been set.
+#if ($field.doc())      * $field.doc()
+#end
+      */
     public boolean ${this.generateHasMethod($schema, $field)}() {
       return fieldSetFlags()[$field.pos()];
     }
-
-    /** Clears the value of the '${this.mangle($field.name(), $schema.isError())}' field */
+
+    /**
+      * Clears the value of the '${this.mangle($field.name(), $schema.isError())}' field.
+#if ($field.doc())      * $field.doc()
+#end
+      */
     public #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder ${this.generateClearMethod($schema, $field)}() {
 #if (${this.isUnboxedJavaTypeNullable($field.schema())})
       ${this.mangle($field.name(), $schema.isError())} = null;

diff --git a/lang/java/tools/src/test/compiler/input/player.avsc b/lang/java/tools/src/test/compiler/input/player.avsc
@@ -1,6 +1,6 @@
 {"type":"record", "name":"Player", "namespace": "avro.examples.baseball","doc":"選手 is Japanese for player.",
   "fields": [
-   {"name": "number", "type": "int"},
+   {"name": "number", "type": "int", "doc": "The number of the player"},
    {"name": "first_name", "type": "string"},
    {"name": "last_name", "type": "string"},
    {"name": "position", "type": {"type": "array", "items": "Position"} }

diff --git a/lang/java/tools/src/test/compiler/output-string/avro/examples/baseball/Player.java b/lang/java/tools/src/test/compiler/output-string/avro/examples/baseball/Player.java
@@ -9,8 +9,9 @@
 @org.apache.avro.specific.AvroGenerated
 public class Player extends org.apache.avro.specific.SpecificRecordBase implements org.apache.avro.specific.SpecificRecord {
   private static final long serialVersionUID = 3865593031278745715L;
-  public static final org.apache.avro.Schema SCHEMA$ = new org.apache.avro.Schema.Parser().parse("{\"type\":\"record\",\"name\":\"Player\",\"namespace\":\"avro.examples.baseball\",\"doc\":\"選手 is Japanese for player.\",\"fields\":[{\"name\":\"number\",\"type\":\"int\"},{\"name\":\"first_name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"last_name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"position\",\"type\":{\"type\":\"array\",\"items\":{\"type\":\"enum\",\"name\":\"Position\",\"symbols\":[\"P\",\"C\",\"B1\",\"B2\",\"B3\",\"SS\",\"LF\",\"CF\",\"RF\",\"DH\"]}}}]}");
+  public static final org.apache.avro.Schema SCHEMA$ = new org.apache.avro.Schema.Parser().parse("{\"type\":\"record\",\"name\":\"Player\",\"namespace\":\"avro.examples.baseball\",\"doc\":\"選手 is Japanese for player.\",\"fields\":[{\"name\":\"number\",\"type\":\"int\",\"doc\":\"The number of the player\"},{\"name\":\"first_name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"last_name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"position\",\"type\":{\"type\":\"array\",\"items\":{\"type\":\"enum\",\"name\":\"Position\",\"symbols\":[\"P\",\"C\",\"B1\",\"B2\",\"B3\",\"SS\",\"LF\",\"CF\",\"RF\",\"DH\"]}}}]}");
   public static org.apache.avro.Schema getClassSchema() { return SCHEMA$; }
+  /** The number of the player */
   @Deprecated public int number;
   @Deprecated public java.lang.String first_name;
   @Deprecated public java.lang.String last_name;
@@ -58,13 +59,15 @@ public void put(int field$, java.lang.Object value$) {
 
   /**
    * Gets the value of the 'number' field.
+   * The number of the player
    */
   public java.lang.Integer getNumber() {
     return number;
   }
 
   /**
    * Sets the value of the 'number' field.
+   * The number of the player
    * @param value the value to set.
    */
   public void setNumber(java.lang.Integer value) {
@@ -189,99 +192,139 @@ private Builder(avro.examples.baseball.Player other) {
       }
     }
 
-    /** Gets the value of the 'number' field */
+    /**
+      * Gets the value of the 'number' field.
+      * The number of the player
+      */
     public java.lang.Integer getNumber() {
       return number;
     }
-
-    /** Sets the value of the 'number' field */
+
+    /**
+      * Sets the value of the 'number' field.
+      * The number of the player
+      * @param value the value to set.
+      */
     public avro.examples.baseball.Player.Builder setNumber(int value) {
       validate(fields()[0], value);
       this.number = value;
       fieldSetFlags()[0] = true;
       return this; 
     }
-
-    /** Checks whether the 'number' field has been set */
+
+    /** 
+      * Checks whether the 'number' field has been set.
+      * The number of the player
+      */
     public boolean hasNumber() {
       return fieldSetFlags()[0];
     }
-
-    /** Clears the value of the 'number' field */
+
+    /**
+      * Clears the value of the 'number' field.
+      * The number of the player
+      */
     public avro.examples.baseball.Player.Builder clearNumber() {
       fieldSetFlags()[0] = false;
       return this;
     }
 
-    /** Gets the value of the 'first_name' field */
+    /**
+      * Gets the value of the 'first_name' field.
+      */
     public java.lang.String getFirstName() {
       return first_name;
     }
-
-    /** Sets the value of the 'first_name' field */
+
+    /**
+      * Sets the value of the 'first_name' field.
+      * @param value the value to set.
+      */
     public avro.examples.baseball.Player.Builder setFirstName(java.lang.String value) {
       validate(fields()[1], value);
       this.first_name = value;
       fieldSetFlags()[1] = true;
       return this; 
     }
-
-    /** Checks whether the 'first_name' field has been set */
+
+    /** 
+      * Checks whether the 'first_name' field has been set.
+      */
     public boolean hasFirstName() {
       return fieldSetFlags()[1];
     }
-
-    /** Clears the value of the 'first_name' field */
+
+    /**
+      * Clears the value of the 'first_name' field.
+      */
     public avro.examples.baseball.Player.Builder clearFirstName() {
       first_name = null;
       fieldSetFlags()[1] = false;
       return this;
     }
 
-    /** Gets the value of the 'last_name' field */
+    /**
+      * Gets the value of the 'last_name' field.
+      */
     public java.lang.String getLastName() {
       return last_name;
     }
-
-    /** Sets the value of the 'last_name' field */
+
+    /**
+      * Sets the value of the 'last_name' field.
+      * @param value the value to set.
+      */
     public avro.examples.baseball.Player.Builder setLastName(java.lang.String value) {
       validate(fields()[2], value);
       this.last_name = value;
       fieldSetFlags()[2] = true;
       return this; 
     }
-
-    /** Checks whether the 'last_name' field has been set */
+
+    /** 
+      * Checks whether the 'last_name' field has been set.
+      */
     public boolean hasLastName() {
       return fieldSetFlags()[2];
     }
-
-    /** Clears the value of the 'last_name' field */
+
+    /**
+      * Clears the value of the 'last_name' field.
+      */
     public avro.examples.baseball.Player.Builder clearLastName() {
       last_name = null;
       fieldSetFlags()[2] = false;
       return this;
     }
 
-    /** Gets the value of the 'position' field */
+    /**
+      * Gets the value of the 'position' field.
+      */
     public java.util.List<avro.examples.baseball.Position> getPosition() {
       return position;
     }
-
-    /** Sets the value of the 'position' field */
+
+    /**
+      * Sets the value of the 'position' field.
+      * @param value the value to set.
+      */
     public avro.examples.baseball.Player.Builder setPosition(java.util.List<avro.examples.baseball.Position> value) {
       validate(fields()[3], value);
       this.position = value;
       fieldSetFlags()[3] = true;
       return this; 
     }
-
-    /** Checks whether the 'position' field has been set */
+
+    /** 
+      * Checks whether the 'position' field has been set.
+      */
     public boolean hasPosition() {
       return fieldSetFlags()[3];
     }
-
-    /** Clears the value of the 'position' field */
+
+    /**
+      * Clears the value of the 'position' field.
+      */
     public avro.examples.baseball.Player.Builder clearPosition() {
       position = null;
       fieldSetFlags()[3] = false;