avro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tomwh...@apache.org
Subject svn commit: r1687779 - in /avro/branches/branch-1.7: ./ lang/java/avro/src/main/java/org/apache/avro/ lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/
Date Fri, 26 Jun 2015 14:40:48 GMT
Author: tomwhite
Date: Fri Jun 26 14:40:47 2015
New Revision: 1687779

URL: http://svn.apache.org/r1687779
Log:
AVRO-1681. Improve generated JavaDocs. Contributed by Charles Gariépy-Ikeson.

Modified:
    avro/branches/branch-1.7/CHANGES.txt
    avro/branches/branch-1.7/lang/java/avro/src/main/java/org/apache/avro/Protocol.java
    avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/fixed.vm
    avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/protocol.vm
    avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm

Modified: avro/branches/branch-1.7/CHANGES.txt
URL: http://svn.apache.org/viewvc/avro/branches/branch-1.7/CHANGES.txt?rev=1687779&r1=1687778&r2=1687779&view=diff
==============================================================================
--- avro/branches/branch-1.7/CHANGES.txt (original)
+++ avro/branches/branch-1.7/CHANGES.txt Fri Jun 26 14:40:47 2015
@@ -18,6 +18,9 @@ Trunk (not yet released)
 
     AVRO-1585. Java: Deprecate Jackson classes in public API. (tomwhite)
 
+    AVRO-1681. Improve generated JavaDocs.
+    (Charles Gariépy-Ikeson via tomwhite)
+
   BUG FIXES
 
     AVRO-1553. Java: MapReduce never uses MapOutputValueSchema (tomwhite)

Modified: avro/branches/branch-1.7/lang/java/avro/src/main/java/org/apache/avro/Protocol.java
URL: http://svn.apache.org/viewvc/avro/branches/branch-1.7/lang/java/avro/src/main/java/org/apache/avro/Protocol.java?rev=1687779&r1=1687778&r2=1687779&view=diff
==============================================================================
--- avro/branches/branch-1.7/lang/java/avro/src/main/java/org/apache/avro/Protocol.java (original)
+++ avro/branches/branch-1.7/lang/java/avro/src/main/java/org/apache/avro/Protocol.java Fri
Jun 26 14:40:47 2015
@@ -478,8 +478,12 @@ public class Protocol extends JsonProper
       if (fieldTypeNode == null)
         throw new SchemaParseException("No param type: "+field);
       String name = fieldNameNode.getTextValue();
+      String fieldDoc = null;
+      JsonNode fieldDocNode = field.get("doc");
+      if (fieldDocNode != null)
+        fieldDoc = fieldDocNode.getTextValue();
       fields.add(new Field(name, Schema.parse(fieldTypeNode,types),
-                           null /* message fields don't have docs */,
+                           fieldDoc,
                            field.get("default")));
     }
     Schema request = Schema.createRecord(fields);

Modified: avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/fixed.vm
URL: http://svn.apache.org/viewvc/avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/fixed.vm?rev=1687779&r1=1687778&r2=1687779&view=diff
==============================================================================
--- avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/fixed.vm
(original)
+++ avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/fixed.vm
Fri Jun 26 14:40:47 2015
@@ -36,7 +36,10 @@ public class ${this.mangle($schema.getNa
     super();
   }
   
-  /** Creates a new ${this.mangle($schema.getName())} with the given bytes */
+  /**
+   * Creates a new ${this.mangle($schema.getName())} with the given bytes.
+   * @param bytes The bytes to create the new ${this.mangle($schema.getName())}. 
+   */
   public ${this.mangle($schema.getName())}(byte[] bytes) {
     super(bytes);
   }

Modified: avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/protocol.vm
URL: http://svn.apache.org/viewvc/avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/protocol.vm?rev=1687779&r1=1687778&r2=1687779&view=diff
==============================================================================
--- avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/protocol.vm
(original)
+++ avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/protocol.vm
Fri Jun 26 14:40:47 2015
@@ -33,9 +33,15 @@ public interface $this.mangle($protocol.
 #set ($name = $e.getKey())
 #set ($message = $e.getValue())
 #set ($response = $message.getResponse())
+  /**
 #if ($message.getDoc())
-  /** $this.escapeForJavadoc($message.getDoc()) */
+   * $this.escapeForJavadoc($message.getDoc())
 #end
+#foreach ($p in $message.getRequest().getFields())##
+#if ($p.doc())   * @param ${this.mangle($p.name())} $p.doc()
+#end
+#end
+   */
 #foreach ($annotation in $this.javaAnnotations($message))
   @$annotation
 #end
@@ -67,9 +73,16 @@ public interface $this.mangle($protocol.
 #set ($response = $message.getResponse())
 ## Generate callback method if the message is not one-way:
 #if (! $message.isOneWay())
+    /**
 #if ($message.getDoc())
-    /** $this.escapeForJavadoc($message.getDoc()) */
+     * $this.escapeForJavadoc($message.getDoc())
+#end
+#foreach ($p in $message.getRequest().getFields())##
+#if ($p.doc())     * @param ${this.mangle($p.name())} $p.doc()
+#end
 #end
+     * @throws java.io.IOException The async call could not be completed.
+     */
     void ${this.mangle($name)}(##
 #foreach ($p in $message.getRequest().getFields())##
 #*      *#${this.javaUnbox($p.schema())} ${this.mangle($p.name())}#if ($velocityHasNext),
#end

Modified: avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm
URL: http://svn.apache.org/viewvc/avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm?rev=1687779&r1=1687778&r2=1687779&view=diff
==============================================================================
--- avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm
(original)
+++ avro/branches/branch-1.7/lang/java/compiler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm
Fri Jun 26 14:40:47 2015
@@ -68,6 +68,10 @@ public class ${this.mangle($schema.getNa
 
   /**
    * All-args constructor.
+#foreach ($field in $schema.getFields())
+#if ($field.doc())   * @param ${this.mangle($field.name())} $field.doc()
+#end
+#end
    */
   public ${this.mangle($schema.getName())}(#foreach($field in $schema.getFields())${this.javaType($field.schema())}
${this.mangle($field.name())}#if($velocityCount < $schema.getFields().size()), #end#end)
{
 #foreach ($field in $schema.getFields())
@@ -105,7 +109,8 @@ public class ${this.mangle($schema.getNa
 #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())   * @return $field.doc()
+#end
    */
   public ${this.javaType($field.schema())} ${this.generateGetMethod($schema, $field)}() {
     return ${this.mangle($field.name(), $schema.isError())};
@@ -114,7 +119,8 @@ public class ${this.mangle($schema.getNa
 #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) {
@@ -123,17 +129,28 @@ public class ${this.mangle($schema.getNa
 #end
 
 #end
-  /** Creates a new ${this.mangle($schema.getName())} RecordBuilder */
+  /**
+   * Creates a new ${this.mangle($schema.getName())} RecordBuilder.
+   * @return A new ${this.mangle($schema.getName())} RecordBuilder
+   */
   public static #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder
newBuilder() {
     return new #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder();
   }
   
-  /** Creates a new ${this.mangle($schema.getName())} RecordBuilder by copying an existing
Builder */
+  /**
+   * Creates a new ${this.mangle($schema.getName())} RecordBuilder by copying an existing
Builder.
+   * @param other The existing builder to copy.
+   * @return A new ${this.mangle($schema.getName())} RecordBuilder
+   */
   public static #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder
newBuilder(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder
other) {
     return new #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder(other);
   }
   
-  /** Creates a new ${this.mangle($schema.getName())} RecordBuilder by copying an existing
$this.mangle($schema.getName()) instance */
+  /**
+   * Creates a new ${this.mangle($schema.getName())} RecordBuilder by copying an existing
$this.mangle($schema.getName()) instance.
+   * @param other The existing instance to copy.
+   * @return A new ${this.mangle($schema.getName())} RecordBuilder
+   */
   public static #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder
newBuilder(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}
other) {
     return new #if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder(other);
   }
@@ -146,6 +163,9 @@ public class ${this.mangle($schema.getNa
     implements#if ($schema.isError()) org.apache.avro.data.ErrorBuilder<${this.mangle($schema.getName())}>#else
org.apache.avro.data.RecordBuilder<${this.mangle($schema.getName())}>#end {
 
 #foreach ($field in $schema.getFields())
+#if ($field.doc())
+    /** $field.doc() */
+#end
     private ${this.javaUnbox($field.schema())} ${this.mangle($field.name(), $schema.isError())};
 #end
 
@@ -154,7 +174,10 @@ public class ${this.mangle($schema.getNa
       super(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.SCHEMA$);
     }
     
-    /** Creates a Builder by copying an existing Builder */
+    /**
+     * Creates a Builder by copying an existing Builder.
+     * @param other The existing Builder to copy.
+     */
     private Builder(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.Builder
other) {
       super(other);
 #foreach ($field in $schema.getFields())
@@ -165,7 +188,10 @@ public class ${this.mangle($schema.getNa
 #end
     }
     
-    /** Creates a Builder by copying an existing $this.mangle($schema.getName()) instance
*/
+    /**
+     * Creates a Builder by copying an existing $this.mangle($schema.getName()) instance
+     * @param other The existing instance to copy.
+     */
     private Builder(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}
other) {
       #if ($schema.isError())super(other)#else
       super(#if ($schema.getNamespace())$schema.getNamespace().#end${this.mangle($schema.getName())}.SCHEMA$)#end;
@@ -204,12 +230,19 @@ public class ${this.mangle($schema.getNa
 #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.
+     * @return The value.
+     */
     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.
+     * @param value The value of '${this.mangle($field.name(), $schema.isError())}'.
+     * @return This builder.
+     */
     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;
@@ -217,12 +250,18 @@ public class ${this.mangle($schema.getNa
       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.
+     * @return True if the '${this.mangle($field.name(), $schema.isError())}' field has been
set, false otherwise.
+     */
     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.
+     * @return This builder.
+     */
     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;



Mime
View raw message