You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by to...@apache.org on 2015/06/26 16:40:48 UTC
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/
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;