From: illia.ihushev Date: Wed, 20 May 2020 11:47:31 +0000 (+0300) Subject: Generate @param for RPC invocation methods X-Git-Tag: v7.0.0~1 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=e8c0ba72799dfd49fb913bc7c1dc8aad2e576478;p=mdsal.git Generate @param for RPC invocation methods Make codegen correctly format javadoc comments with @return, @param, @throws. This is accomplished by splitting the member comment into three distinct pieces in TypeMemberComment: - a common header: 'Invoke {@code rpc_name_here} RPC.' - a description-based block - a common footer, describing param/return/throws declarations These are communicated from type generator and composed into javadoc by the templating code. JIRA: MDSAL-402 Change-Id: Ia6b7537cbeb28f9e7ff68479e887ab32e92a1c4b Signed-off-by: illia.ihushev Signed-off-by: Robert Varga --- diff --git a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMember.java b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMember.java index 353c66e7a3..76b93a3ebc 100644 --- a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMember.java +++ b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMember.java @@ -8,18 +8,18 @@ package org.opendaylight.mdsal.binding.model.api; import java.util.List; +import org.eclipse.jdt.annotation.Nullable; /** * Common interface for variables and methods in class. */ public interface TypeMember { - /** * Returns comment string associated with member. * * @return comment string associated with member. */ - String getComment(); + @Nullable TypeMemberComment getComment(); /** * Returns List of annotation definitions associated with generated type. @@ -69,5 +69,4 @@ public interface TypeMember { * @return the Type that declares member. */ Type getDefiningType(); - } diff --git a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMemberComment.java b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMemberComment.java new file mode 100644 index 0000000000..f386ce9887 --- /dev/null +++ b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMemberComment.java @@ -0,0 +1,114 @@ +/* + * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.mdsal.binding.model.api; + +import static java.util.Objects.requireNonNull; + +import com.google.common.annotations.Beta; +import com.google.common.base.MoreObjects; +import java.util.Objects; +import org.eclipse.jdt.annotation.NonNull; +import org.eclipse.jdt.annotation.Nullable; +import org.opendaylight.yangtools.concepts.Immutable; + +/** + * Structured comment of a particular class member. This is aimed towards unifying the layout of a particular type. + */ +@Beta +public final class TypeMemberComment implements Immutable { + private final String contractDescription; + private final String referenceDescription; + private final String typeSignature; + + public TypeMemberComment(final String contractDescription, final String referenceDescription, + final String typeSignature) { + this.contractDescription = contractDescription; + this.referenceDescription = referenceDescription; + this.typeSignature = typeSignature; + } + + /** + * Return the member contract description. This string, if present will represent the equivalent of the words you + * are just reading. This forms what is usually: + *
    + *
  • hand-written with careful explanation
    • + *
  • describing the general contract outline, what the member does/holds/etc. For methods this might be pre- + * and post-conditions.
    • + *
+ * + * @return The equivalent of the above blurb. + */ + public @Nullable String contractDescription() { + return contractDescription; + } + + /** + * Return the member reference description. This description is passed unmodified, pre-formatted in a single block. + * It is expected to look something like the following paragraph: + * + *

+ * 

+     *   
+     *     A 32-bit bit unsigned word. Individual bits are expected to be interpreted as follows:
+     *
+     *       31
+     *     +----+ ...
+     *   
+     *
+ * + * @return The equivalent of the above pre-formmated paragraph. + */ + public @Nullable String referenceDescription() { + return referenceDescription; + } + + /** + * Return the type signature of this type member. This is only applicable for methods, use of anywhere else is + * expected to either be ignored, or processed as is. As a matter of example, this method has a signature starting + * right after this period. + * + * @return Return the signature description, just like these words right here + */ + public @Nullable String typeSignature() { + return typeSignature; + } + + public static @NonNull TypeMemberComment contractOf(final String contractDescription) { + return new TypeMemberComment(requireNonNull(contractDescription), null, null); + } + + public static @NonNull TypeMemberComment referenceOf(final String referenceDescription) { + return new TypeMemberComment(null, requireNonNull(referenceDescription), null); + } + + @Override + public int hashCode() { + return Objects.hash(contractDescription, referenceDescription, typeSignature); + } + + @Override + public boolean equals(final Object obj) { + if (obj == this) { + return true; + } + if (!(obj instanceof TypeMemberComment)) { + return false; + } + final TypeMemberComment other = (TypeMemberComment) obj; + return Objects.equals(contractDescription, other.contractDescription) + && Objects.equals(referenceDescription, other.referenceDescription) + && Objects.equals(typeSignature, other.typeSignature); + } + + @Override + public String toString() { + return MoreObjects.toStringHelper(this).omitNullValues() + .add("contract", contractDescription).add("reference", referenceDescription).add("type", typeSignature) + .toString(); + } +} diff --git a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/MethodSignatureBuilder.java b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/MethodSignatureBuilder.java index 5e69bef48b..ce02ba4c09 100644 --- a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/MethodSignatureBuilder.java +++ b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/MethodSignatureBuilder.java @@ -11,6 +11,7 @@ import com.google.common.annotations.Beta; import org.opendaylight.mdsal.binding.model.api.MethodSignature; import org.opendaylight.mdsal.binding.model.api.MethodSignature.ValueMechanics; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; /** * Method Signature Builder serves solely for building Method Signature and @@ -21,7 +22,7 @@ import org.opendaylight.mdsal.binding.model.api.Type; * addName due to enforce reason that MethodSignatureBuilder SHOULD be * instantiated only once with defined method name.
* The methods as {@link #addAnnotation(String, String)} and - * {@link #setComment(String)} can be used as optional because not all methods + * {@link #setComment(TypeMemberComment)} can be used as optional because not all methods * MUST contain annotation or comment definitions. * * @see MethodSignature diff --git a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/TypeMemberBuilder.java b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/TypeMemberBuilder.java index ddb84d6eca..2f0e204d0c 100644 --- a/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/TypeMemberBuilder.java +++ b/binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/type/builder/TypeMemberBuilder.java @@ -9,6 +9,7 @@ package org.opendaylight.mdsal.binding.model.api.type.builder; import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; public interface TypeMemberBuilder> extends AnnotableTypeBuilder { /** @@ -39,9 +40,9 @@ public interface TypeMemberBuilder> extends Annot * Adds String definition of comment into Method Signature definition. The comment String MUST NOT contain any * comment specific chars (i.e. "/**" or "//") just plain String text description. * - * @param comment Comment String. + * @param comment Structured comment */ - T setComment(String comment); + T setComment(TypeMemberComment comment); /** * Sets the flag final for method signature. If this is set the method will be prohibited from overriding. This diff --git a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/AbstractTypeGenerator.java b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/AbstractTypeGenerator.java index 1c8b7da099..afed7fe272 100644 --- a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/AbstractTypeGenerator.java +++ b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/AbstractTypeGenerator.java @@ -245,6 +245,8 @@ abstract class AbstractTypeGenerator { abstract void addComment(TypeMemberBuilder genType, DocumentedNode node); + abstract void addRpcMethodComment(TypeMemberBuilder genType, RpcDefinition node); + private ModuleContext moduleToGenTypes(final Module module) { final ModuleContext context = new ModuleContext(module); genCtx.put(module.getQNameModule(), context); @@ -559,7 +561,7 @@ abstract class AbstractTypeGenerator { // Do not refer to annotation class, as it may not be available at runtime method.addAnnotation(CHECK_RETURN_VALUE_ANNOTATION); - addComment(method, rpc); + addRpcMethodComment(method, rpc); method.addParameter( createRpcContainer(context, rpcName, rpc, verifyNotNull(rpc.getInput()), RPC_INPUT), "input"); method.setReturnType(listenableFutureTypeFor( diff --git a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/CodegenTypeGenerator.java b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/CodegenTypeGenerator.java index 2365033583..3d40e877d9 100644 --- a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/CodegenTypeGenerator.java +++ b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/CodegenTypeGenerator.java @@ -7,16 +7,14 @@ */ package org.opendaylight.mdsal.binding.generator.impl; -import static org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.encodeAngleBrackets; - import java.util.ArrayList; import java.util.Collection; import java.util.List; import java.util.Map; -import java.util.Optional; import java.util.Set; import org.opendaylight.mdsal.binding.model.api.JavaTypeName; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition; import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder; import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilderBase; @@ -26,6 +24,7 @@ import org.opendaylight.mdsal.binding.yang.types.CodegenTypeProvider; import org.opendaylight.yangtools.yang.model.api.DocumentedNode; import org.opendaylight.yangtools.yang.model.api.EffectiveModelContext; import org.opendaylight.yangtools.yang.model.api.Module; +import org.opendaylight.yangtools.yang.model.api.RpcDefinition; import org.opendaylight.yangtools.yang.model.api.SchemaNode; final class CodegenTypeGenerator extends AbstractTypeGenerator { @@ -72,9 +71,16 @@ final class CodegenTypeGenerator extends AbstractTypeGenerator { @Override void addComment(final TypeMemberBuilder genType, final DocumentedNode node) { - final Optional optDesc = node.getDescription(); - if (optDesc.isPresent()) { - genType.setComment(encodeAngleBrackets(optDesc.get())); - } + node.getDescription().map(TypeMemberComment::referenceOf).ifPresent(genType::setComment); + } + + @Override + void addRpcMethodComment(final TypeMemberBuilder genType, final RpcDefinition node) { + final String rpcName = node.getQName().getLocalName(); + genType.setComment(new TypeMemberComment( + "Invoke {@code " + rpcName + "} RPC.", + node.getDescription().orElse(null), + "@param input of {@code " + rpcName + "}\n" + + "@return output of {@code " + rpcName + '}')); } } diff --git a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/RuntimeTypeGenerator.java b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/RuntimeTypeGenerator.java index 07794f0341..b49457ad5d 100644 --- a/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/RuntimeTypeGenerator.java +++ b/binding/mdsal-binding-generator-impl/src/main/java/org/opendaylight/mdsal/binding/generator/impl/RuntimeTypeGenerator.java @@ -31,6 +31,7 @@ import org.opendaylight.yangtools.yang.model.api.DocumentedNode; import org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus; import org.opendaylight.yangtools.yang.model.api.EffectiveModelContext; import org.opendaylight.yangtools.yang.model.api.Module; +import org.opendaylight.yangtools.yang.model.api.RpcDefinition; import org.opendaylight.yangtools.yang.model.api.SchemaNode; final class RuntimeTypeGenerator extends AbstractTypeGenerator { @@ -102,4 +103,9 @@ final class RuntimeTypeGenerator extends AbstractTypeGenerator { void addComment(final TypeMemberBuilder genType, final DocumentedNode node) { // No-op } + + @Override + void addRpcMethodComment(final TypeMemberBuilder genType, final RpcDefinition node) { + // No-op + } } diff --git a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMember.java b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMember.java index ade89ea227..b9c5aa1526 100644 --- a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMember.java +++ b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMember.java @@ -13,11 +13,12 @@ import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.AnnotationType; import org.opendaylight.mdsal.binding.model.api.Type; import org.opendaylight.mdsal.binding.model.api.TypeMember; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; abstract class AbstractTypeMember implements TypeMember { private final String name; - private final String comment; + private final TypeMemberComment comment; private final Type definingType; private final Type returnType; private final List annotations; @@ -26,7 +27,7 @@ abstract class AbstractTypeMember implements TypeMember { private final AccessModifier accessModifier; protected AbstractTypeMember(final Type definingType, final String name, final List annotations, - final String comment, final AccessModifier accessModifier, final Type returnType, + final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType, final boolean isFinal, final boolean isStatic) { this.definingType = definingType; this.name = name; @@ -49,8 +50,8 @@ abstract class AbstractTypeMember implements TypeMember { } @Override - public String getComment() { - return this.comment; + public TypeMemberComment getComment() { + return comment; } @Override @@ -80,11 +81,7 @@ abstract class AbstractTypeMember implements TypeMember { @Override public int hashCode() { - final int prime = 31; - int result = 1; - result = (prime * result) + Objects.hashCode(getName()); - result = (prime * result) + Objects.hashCode(getReturnType()); - return result; + return Objects.hash(getName(), getReturnType()); } @Override @@ -92,10 +89,7 @@ abstract class AbstractTypeMember implements TypeMember { if (this == obj) { return true; } - if (obj == null) { - return false; - } - if (getClass() != obj.getClass()) { + if (obj == null || getClass() != obj.getClass()) { return false; } final AbstractTypeMember other = (AbstractTypeMember) obj; @@ -104,24 +98,17 @@ abstract class AbstractTypeMember implements TypeMember { @Override public String toString() { - final StringBuilder builder = new StringBuilder(); - builder.append("AbstractTypeMember [name="); - builder.append(getName()); - builder.append(", comment="); - builder.append(getComment()); + final StringBuilder builder = new StringBuilder() + .append("AbstractTypeMember [name=").append(getName()) + .append(", comment=").append(getComment()) + .append(", definingType="); if (getDefiningType() != null) { - builder.append(", definingType="); - builder.append(getDefiningType().getPackageName()); - builder.append("."); - builder.append(getDefiningType().getName()); + builder.append(getDefiningType().getPackageName()).append('.').append(getDefiningType().getName()); } else { - builder.append(", definingType= null"); + builder.append(" null"); } - builder.append(", returnType="); - builder.append(getReturnType()); - builder.append(", annotations="); - builder.append(getAnnotations()); - builder.append("]"); - return builder.toString(); + return builder.append(", returnType=").append(getReturnType()) + .append(", annotations=").append(getAnnotations()) + .append(']').toString(); } } diff --git a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberBuilder.java b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberBuilder.java index 75a24ad475..da85b500c1 100644 --- a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberBuilder.java +++ b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberBuilder.java @@ -18,6 +18,7 @@ import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.AnnotationType; import org.opendaylight.mdsal.binding.model.api.JavaTypeName; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; import org.opendaylight.mdsal.binding.model.api.type.builder.AnnotationTypeBuilder; import org.opendaylight.mdsal.binding.model.api.type.builder.TypeMemberBuilder; import org.opendaylight.yangtools.util.LazyCollections; @@ -26,7 +27,7 @@ abstract class AbstractTypeMemberBuilder> impleme private final String name; private Type returnType; private List annotationBuilders = Collections.emptyList(); - private String comment = ""; + private TypeMemberComment comment; private boolean isFinal; private boolean isStatic; private AccessModifier accessModifier; @@ -50,7 +51,7 @@ abstract class AbstractTypeMemberBuilder> impleme return this.annotationBuilders; } - protected String getComment() { + protected TypeMemberComment getComment() { return this.comment; } @@ -89,7 +90,7 @@ abstract class AbstractTypeMemberBuilder> impleme } @Override - public T setComment(final String newComment) { + public T setComment(final TypeMemberComment newComment) { this.comment = newComment; return thisInstance(); } diff --git a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImpl.java b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImpl.java index 07e5492297..ca406eadde 100644 --- a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImpl.java +++ b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImpl.java @@ -49,22 +49,14 @@ public final class GeneratedPropertyBuilderImpl extends AbstractTypeMemberBuilde @Override public String toString() { - final StringBuilder builder = new StringBuilder(); - builder.append("GeneratedPropertyImpl [name="); - builder.append(getName()); - builder.append(", annotations="); - builder.append(getAnnotationBuilders()); - builder.append(", comment="); - builder.append(getComment()); - builder.append(", returnType="); - builder.append(getReturnType()); - builder.append(", isFinal="); - builder.append(isFinal()); - builder.append(", isReadOnly="); - builder.append(this.readOnly); - builder.append(", modifier="); - builder.append(getAccessModifier()); - builder.append("]"); - return builder.toString(); + return new StringBuilder() + .append("GeneratedPropertyImpl [name=").append(getName()) + .append(", annotations=").append(getAnnotationBuilders()) + .append(", comment=").append(getComment()) + .append(", returnType=").append(getReturnType()) + .append(", isFinal=").append(isFinal()) + .append(", isReadOnly=").append(this.readOnly) + .append(", modifier=").append(getAccessModifier()) + .append(']').toString(); } } \ No newline at end of file diff --git a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImpl.java b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImpl.java index c83aefb7a6..166e893312 100644 --- a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImpl.java +++ b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImpl.java @@ -12,14 +12,15 @@ import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.AnnotationType; import org.opendaylight.mdsal.binding.model.api.GeneratedProperty; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; final class GeneratedPropertyImpl extends AbstractTypeMember implements GeneratedProperty { private final String value; private final boolean readOnly; GeneratedPropertyImpl(final Type definingType, final String name, final List annotations, - final String comment, final AccessModifier accessModifier, final Type returnType, final boolean isFinal, - final boolean isStatic, final boolean isReadOnly, final String value) { + final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType, + final boolean isFinal, final boolean isStatic, final boolean isReadOnly, final String value) { super(definingType, name, annotations, comment, accessModifier, returnType, isFinal, isStatic); this.value = value; this.readOnly = isReadOnly; @@ -37,30 +38,20 @@ final class GeneratedPropertyImpl extends AbstractTypeMember implements Generate @Override public String toString() { - final StringBuilder builder = new StringBuilder(); - builder.append("GeneratedPropertyImpl [name="); - builder.append(getName()); - builder.append(", annotations="); - builder.append(getAnnotations()); - builder.append(", comment="); - builder.append(getComment()); + final StringBuilder builder = new StringBuilder() + .append("GeneratedPropertyImpl [name=").append(getName()) + .append(", annotations=").append(getAnnotations()) + .append(", comment=").append(getComment()) + .append(", parent="); if (getDefiningType() != null) { - builder.append(", parent="); - builder.append(getDefiningType().getPackageName()); - builder.append("."); - builder.append(getDefiningType().getName()); + builder.append(getDefiningType().getPackageName()).append(".").append(getDefiningType().getName()); } else { - builder.append(", parent=null"); + builder.append("null"); } - builder.append(", returnType="); - builder.append(getReturnType()); - builder.append(", isFinal="); - builder.append(isFinal()); - builder.append(", isReadOnly="); - builder.append(this.readOnly); - builder.append(", modifier="); - builder.append(getAccessModifier()); - builder.append("]"); - return builder.toString(); + return builder.append(", returnType=").append(getReturnType()) + .append(", isFinal=").append(isFinal()) + .append(", isReadOnly=").append(readOnly) + .append(", modifier=").append(getAccessModifier()) + .append(']').toString(); } } diff --git a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureBuilderImpl.java b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureBuilderImpl.java index fa60f84a92..7e1b9d16ae 100644 --- a/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureBuilderImpl.java +++ b/binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureBuilderImpl.java @@ -21,7 +21,6 @@ import org.opendaylight.yangtools.util.LazyCollections; final class MethodSignatureBuilderImpl extends AbstractTypeMemberBuilder implements MethodSignatureBuilder { - private List parameters = Collections.emptyList(); private List unmodifiableParams = Collections.emptyList(); private ValueMechanics mechanics = ValueMechanics.NORMAL; @@ -71,12 +70,7 @@ final class MethodSignatureBuilderImpl extends AbstractTypeMemberBuilder params; @@ -26,14 +27,14 @@ class MethodSignatureImpl extends AbstractTypeMember implements MethodSignature @VisibleForTesting MethodSignatureImpl(final Type definingType, final String name, final List annotations, - final String comment, final AccessModifier accessModifier, final Type returnType, + final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType, final List params, final boolean isFinal, final boolean isAbstract, final boolean isStatic) { this(definingType, name, annotations, comment, accessModifier, returnType, params, isFinal, isAbstract, isStatic, false, ValueMechanics.NORMAL); } MethodSignatureImpl(final Type definingType, final String name, final List annotations, - final String comment, final AccessModifier accessModifier, final Type returnType, + final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType, final List params, final boolean isFinal, final boolean isAbstract, final boolean isStatic, final boolean isDefault, final ValueMechanics mechanics) { super(definingType, name, annotations, comment, accessModifier, returnType, isFinal, isStatic); @@ -89,9 +90,10 @@ class MethodSignatureImpl extends AbstractTypeMember implements MethodSignature @Override public String toString() { - final StringBuilder builder = new StringBuilder().append("MethodSignatureImpl [name=").append(getName()) - .append(", comment=").append(getComment()) - .append(", definingType="); + final StringBuilder builder = new StringBuilder() + .append("MethodSignatureImpl [name=").append(getName()) + .append(", comment=").append(getComment()) + .append(", definingType="); final Type defType = getDefiningType(); if (defType != null) { @@ -100,9 +102,10 @@ class MethodSignatureImpl extends AbstractTypeMember implements MethodSignature builder.append(" null"); } - return builder.append(", returnType=").append(getReturnType()) - .append(", params=").append(this.params) - .append(", annotations=").append(getAnnotations()) - .append(']').toString(); + return builder + .append(", returnType=").append(getReturnType()) + .append(", params=").append(this.params) + .append(", annotations=").append(getAnnotations()) + .append(']').toString(); } } diff --git a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberTest.java b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberTest.java index c334119c0c..c512bb192f 100644 --- a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberTest.java +++ b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/AbstractTypeMemberTest.java @@ -15,6 +15,7 @@ import static org.junit.Assert.assertTrue; import org.junit.Test; import org.opendaylight.mdsal.binding.model.api.JavaTypeName; import org.opendaylight.mdsal.binding.model.api.MethodSignature; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; public class AbstractTypeMemberTest { @@ -25,13 +26,13 @@ public class AbstractTypeMemberTest { JavaTypeName.create("org.opendaylight.yangtools.test", "TestType")); final CodegenGeneratedTypeBuilder typeBuilderImpl2 = new CodegenGeneratedTypeBuilder( JavaTypeName.create("org.opendaylight.yangtools.test", "TestType2")); - methodSignatureBuilderImpl.setComment("test comment"); + methodSignatureBuilderImpl.setComment(TypeMemberComment.contractOf("test comment")); methodSignatureBuilderImpl.setFinal(true); methodSignatureBuilderImpl.setStatic(true); final MethodSignature genProperty = methodSignatureBuilderImpl.toInstance(typeBuilderImpl); final MethodSignature genProperty2 = methodSignatureBuilderImpl.toInstance(typeBuilderImpl2); - assertEquals("test comment", genProperty.getComment()); + assertEquals(TypeMemberComment.contractOf("test comment"), genProperty.getComment()); assertTrue(genProperty.isFinal()); assertTrue(genProperty.isStatic()); assertEquals(genProperty.hashCode(), genProperty2.hashCode()); @@ -39,6 +40,5 @@ public class AbstractTypeMemberTest { assertNotNull(genProperty.toString()); assertTrue(genProperty.equals(genProperty2)); assertFalse(genProperty.equals(null)); - } } diff --git a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImplTest.java b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImplTest.java index 779725427e..e60d763b5a 100644 --- a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImplTest.java +++ b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyBuilderImplTest.java @@ -10,6 +10,7 @@ package org.opendaylight.mdsal.binding.model.util.generated.type.builder; import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertFalse; import static org.junit.Assert.assertNotNull; +import static org.junit.Assert.assertNull; import static org.junit.Assert.assertTrue; import org.junit.Test; @@ -42,7 +43,7 @@ public class GeneratedPropertyBuilderImplTest { assertTrue(instance.isStatic()); assertFalse(instance.isReadOnly()); assertEquals("myValue", instance.getValue()); - assertEquals(null, instance.getComment()); + assertNull(instance.getComment()); assertEquals(AccessModifier.PUBLIC, instance.getAccessModifier()); assertEquals(Types.BOOLEAN, instance.getReturnType()); diff --git a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImplTest.java b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImplTest.java index 420ac7c8c3..3e05d8e788 100644 --- a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImplTest.java +++ b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyImplTest.java @@ -16,6 +16,7 @@ import org.junit.Test; import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.GeneratedProperty; import org.opendaylight.mdsal.binding.model.api.JavaTypeName; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; import org.opendaylight.mdsal.binding.model.util.Types; public class GeneratedPropertyImplTest { @@ -26,7 +27,7 @@ public class GeneratedPropertyImplTest { generatedPropertyBuilderImpl.setValue("myValue"); generatedPropertyBuilderImpl.setReadOnly(false); generatedPropertyBuilderImpl.setStatic(true); - generatedPropertyBuilderImpl.setComment("myComment"); + generatedPropertyBuilderImpl.setComment(TypeMemberComment.contractOf("myComment")); generatedPropertyBuilderImpl.setFinal(true); generatedPropertyBuilderImpl.setAccessModifier(AccessModifier.PUBLIC); generatedPropertyBuilderImpl.setReturnType(Types.BOOLEAN); @@ -40,13 +41,14 @@ public class GeneratedPropertyImplTest { assertTrue(instance.isStatic()); assertFalse(instance.isReadOnly()); assertEquals("myValue", instance.getValue()); - assertEquals("myComment", instance.getComment()); + assertEquals(TypeMemberComment.contractOf("myComment"), instance.getComment()); assertEquals(AccessModifier.PUBLIC, instance.getAccessModifier()); assertEquals(Types.BOOLEAN, instance.getReturnType()); - assertEquals("GeneratedPropertyImpl [name=myPropertyName, annotations=[], comment=myComment, " - + "parent=my.package.myTypeName, returnType=Type (java.lang.Boolean), isFinal=true, isReadOnly=false, " - + "modifier=PUBLIC]", instance.toString()); + assertEquals("GeneratedPropertyImpl [name=myPropertyName, annotations=[], " + + "comment=TypeMemberComment{contract=myComment}, " + + "parent=my.package.myTypeName, returnType=Type (java.lang.Boolean), isFinal=true, isReadOnly=false, " + + "modifier=PUBLIC]", instance.toString()); } @Test diff --git a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyTest.java b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyTest.java index 5e3ef4e37f..00e3dc7d50 100644 --- a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyTest.java +++ b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/GeneratedPropertyTest.java @@ -14,6 +14,7 @@ import static org.junit.Assert.assertTrue; import org.junit.Test; import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.GeneratedProperty; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; public class GeneratedPropertyTest { @@ -32,8 +33,9 @@ public class GeneratedPropertyTest { @Test public void testMethodsForGeneratedPropertyImpl() { - final GeneratedPropertyImpl propertyImpl = new GeneratedPropertyImpl(null, "Test", null, "test property", - AccessModifier.PRIVATE, null, true, true, true, "test value"); + final GeneratedPropertyImpl propertyImpl = new GeneratedPropertyImpl(null, "Test", null, + TypeMemberComment.contractOf("test property"), AccessModifier.PRIVATE, null, true, true, true, + "test value"); assertEquals("test value", propertyImpl.getValue()); assertTrue(propertyImpl.isReadOnly()); diff --git a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureImplTest.java b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureImplTest.java index b480eb9c89..0558438538 100644 --- a/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureImplTest.java +++ b/binding/mdsal-binding-generator-util/src/test/java/org/opendaylight/mdsal/binding/model/util/generated/type/builder/MethodSignatureImplTest.java @@ -9,6 +9,7 @@ package org.opendaylight.mdsal.binding.model.util.generated.type.builder; import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNotEquals; import static org.junit.Assert.assertTrue; import java.util.ArrayList; @@ -19,6 +20,7 @@ import org.opendaylight.mdsal.binding.model.api.AccessModifier; import org.opendaylight.mdsal.binding.model.api.AnnotationType; import org.opendaylight.mdsal.binding.model.api.MethodSignature.Parameter; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; import org.opendaylight.mdsal.binding.model.util.Types; public class MethodSignatureImplTest { @@ -35,7 +37,7 @@ public class MethodSignatureImplTest { Type type = Types.STRING; String name = "customMethod"; List annotations = new ArrayList<>(); - String comment = "This is just a comment"; + TypeMemberComment comment = TypeMemberComment.contractOf("This is just a comment"); AccessModifier accessModifier = AccessModifier.PUBLIC; Type returnType = Types.STRING; List params = new ArrayList<>(); @@ -71,7 +73,7 @@ public class MethodSignatureImplTest { @Test public void testHashCode() { assertEquals(hash1, hash1); - assertTrue(!(hash1 == hash4)); + assertNotEquals(hash1, hash4); } @Test diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BaseTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BaseTemplate.xtend index 5528a65733..e6a0a9be30 100644 --- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BaseTemplate.xtend +++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BaseTemplate.xtend @@ -7,7 +7,8 @@ */ package org.opendaylight.mdsal.binding.java.api.generator -import static org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.encodeAngleBrackets +import static extension org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.encodeAngleBrackets +import static extension org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.replaceAllIllegalChars import com.google.common.base.CharMatcher import com.google.common.base.Splitter @@ -32,9 +33,9 @@ import org.opendaylight.mdsal.binding.model.api.MethodSignature import org.opendaylight.mdsal.binding.model.api.Restrictions import org.opendaylight.mdsal.binding.model.api.Type import org.opendaylight.mdsal.binding.model.api.TypeMember +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition.Single import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition.Multiple -import org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil import org.opendaylight.mdsal.binding.model.util.TypeConstants import org.opendaylight.mdsal.binding.model.util.Types import org.opendaylight.mdsal.binding.spec.naming.BindingMapping @@ -102,7 +103,7 @@ abstract class BaseTemplate extends JavaFileTemplate { "_" + property.name } - final protected def propertyNameFromGetter(MethodSignature getter) { + final protected static def propertyNameFromGetter(MethodSignature getter) { var String prefix; if (getter.name.startsWith(BindingMapping.BOOLEAN_GETTER_PREFIX)) { prefix = BindingMapping.BOOLEAN_GETTER_PREFIX @@ -193,13 +194,17 @@ abstract class BaseTemplate extends JavaFileTemplate { * @param comment string with the comment for whole JAVA class * @return string with comment in JAVA format */ - def protected CharSequence asJavadoc(String comment) { + def final protected asJavadoc(TypeMemberComment comment) { if (comment === null) { return '' } - return ''' - «wrapToDocumentation(formatToParagraph(comment.trim))» - ''' + return wrapToDocumentation(''' + «comment.contractDescription» + + «comment.referenceDescription.formatReference» + + «comment.typeSignature» + ''') } def static String wrapToDocumentation(String text) { @@ -313,7 +318,7 @@ abstract class BaseTemplate extends JavaFileTemplate { def private static void appendYangSnippet(StringBuilder sb, ModuleEffectiveStatement module, DeclaredStatement stmt) { for (String str : YANG_FORMATTER.toYangTextSnippet(module, stmt)) { - sb.append(BindingGeneratorUtil.replaceAllIllegalChars(encodeAngleBrackets(encodeJavadocSymbols(str)))) + sb.append(str.encodeJavadocSymbols.encodeAngleBrackets.replaceAllIllegalChars) } } @@ -338,24 +343,16 @@ abstract class BaseTemplate extends JavaFileTemplate { return sb.toString(); } - def protected static String formatDataForJavaDoc(TypeMember type, String additionalComment) { - val StringBuilder typeDescriptionBuilder = new StringBuilder(); - if (!type.comment.nullOrEmpty) { - typeDescriptionBuilder.append(formatToParagraph(type.comment)) - typeDescriptionBuilder.append(NEW_LINE) - typeDescriptionBuilder.append(NEW_LINE) - typeDescriptionBuilder.append(NEW_LINE) - } - typeDescriptionBuilder.append(additionalComment) - var typeDescription = wrapToDocumentation(typeDescriptionBuilder.toString) - return ''' - «typeDescription» - '''.toString - } + def static formatReference(String reference) ''' + «IF reference !== null» + 
+                
+                    «reference.encodeAngleBrackets.formatToParagraph»
+                
+
- def asCode(String text) { - return "" + text + "" - } + «ENDIF» + ''' def asLink(String text) { val StringBuilder sb = new StringBuilder() @@ -380,21 +377,15 @@ abstract class BaseTemplate extends JavaFileTemplate { return sb.toString } - protected static def formatToParagraph(String text) { - if(text === null || text.isEmpty) - return text - - var formattedText = text + protected static def formatToParagraph(String inputText) { val StringBuilder sb = new StringBuilder(); var StringBuilder lineBuilder = new StringBuilder(); var boolean isFirstElementOnNewLineEmptyChar = false; - formattedText = encodeJavadocSymbols(formattedText) - formattedText = WS_MATCHER.replaceFrom(formattedText, SPACE) + var formattedText = WS_MATCHER.replaceFrom(inputText.encodeJavadocSymbols, SPACE) formattedText = SPACES_PATTERN.matcher(formattedText).replaceAll(" ") - val StringTokenizer tokenizer = new StringTokenizer(formattedText, " ", true); - + val StringTokenizer tokenizer = new StringTokenizer(formattedText, " ", true) while (tokenizer.hasMoreTokens) { val nextElement = tokenizer.nextToken @@ -413,7 +404,6 @@ abstract class BaseTemplate extends JavaFileTemplate { isFirstElementOnNewLineEmptyChar = !isFirstElementOnNewLineEmptyChar; } } - if (isFirstElementOnNewLineEmptyChar) { isFirstElementOnNewLineEmptyChar = !isFirstElementOnNewLineEmptyChar } else { diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderGeneratedProperty.java b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderGeneratedProperty.java index d884dcf944..3f7510ea2d 100644 --- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderGeneratedProperty.java +++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderGeneratedProperty.java @@ -16,6 +16,7 @@ import org.opendaylight.mdsal.binding.model.api.GeneratedProperty; import org.opendaylight.mdsal.binding.model.api.MethodSignature; import org.opendaylight.mdsal.binding.model.api.MethodSignature.ValueMechanics; import org.opendaylight.mdsal.binding.model.api.Type; +import org.opendaylight.mdsal.binding.model.api.TypeMemberComment; final class BuilderGeneratedProperty implements GeneratedProperty { private final MethodSignature getter; @@ -62,7 +63,7 @@ final class BuilderGeneratedProperty implements GeneratedProperty { } @Override - public String getComment() { + public TypeMemberComment getComment() { throw uoe(); } diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ClassTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ClassTemplate.xtend index 3199d9122d..4ee8d603f9 100644 --- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ClassTemplate.xtend +++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ClassTemplate.xtend @@ -148,7 +148,7 @@ class ClassTemplate extends BaseTemplate { * @return string with class source code in JAVA format */ def protected generateBody(boolean isInnerClass) ''' - «wrapToDocumentation(formatDataForJavaDoc(type))» + «type.formatDataForJavaDoc.wrapToDocumentation» «annotationDeclaration» «generateClassDeclaration(isInnerClass)» { «suidDeclaration» diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/EnumTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/EnumTemplate.xtend index 51cfab310e..ccc6b4390e 100644 --- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/EnumTemplate.xtend +++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/EnumTemplate.xtend @@ -7,7 +7,7 @@ */ package org.opendaylight.mdsal.binding.java.api.generator -import static org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.encodeAngleBrackets +import static extension org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.encodeAngleBrackets import static org.opendaylight.mdsal.binding.model.util.Types.STRING; import com.google.common.collect.ImmutableMap @@ -55,7 +55,9 @@ class EnumTemplate extends BaseTemplate { } def writeEnumItem(String name, String mappedName, int value, String description) ''' - «asJavadoc(encodeAngleBrackets(description))» + «IF description !== null» + «description.trim.encodeAngleBrackets.encodeJavadocSymbols.wrapToDocumentation» + «ENDIF» «mappedName»(«value», "«name»") ''' @@ -65,7 +67,7 @@ class EnumTemplate extends BaseTemplate { * @return string with the enumeration body */ override body() ''' - «wrapToDocumentation(formatDataForJavaDoc(enums))» + «enums.formatDataForJavaDoc.wrapToDocumentation» public enum «enums.name» implements «org.opendaylight.yangtools.yang.binding.Enumeration.importedName» { «writeEnumeration(enums)» diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/InterfaceTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/InterfaceTemplate.xtend index 7780cbd510..ac67e96555 100644 --- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/InterfaceTemplate.xtend +++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/InterfaceTemplate.xtend @@ -31,6 +31,7 @@ import org.opendaylight.mdsal.binding.model.api.MethodSignature import org.opendaylight.mdsal.binding.model.api.Type import org.opendaylight.mdsal.binding.model.util.Types import org.opendaylight.mdsal.binding.model.util.TypeConstants +import org.opendaylight.mdsal.binding.model.api.TypeMember /** * Template for generating JAVA interfaces. @@ -79,7 +80,7 @@ class InterfaceTemplate extends BaseTemplate { * @return string with code for interface body in JAVA format */ override body() ''' - «wrapToDocumentation(formatDataForJavaDoc(type))» + «type.formatDataForJavaDoc.wrapToDocumentation» «type.annotations.generateAnnotations» public interface «type.name» «superInterfaces» @@ -207,12 +208,25 @@ class InterfaceTemplate extends BaseTemplate { «method.returnType.importedName» «method.name»(«method.parameters.generateParameters»); ''' - def private generateAccessorMethod(MethodSignature method) ''' - «val ret = method.returnType» - «formatDataForJavaDoc(method, "@return " + asCode(ret.fullyQualifiedName) + " " + asCode(propertyNameFromGetter(method)) + ", or " + asCode("null") + " if not present")» - «method.annotations.generateAnnotations» - «nullableType(ret)» «method.name»(); - ''' + def private static accessorJavadoc(MethodSignature method, String orString) { + val reference = method.comment?.referenceDescription + val propReturn = method.propertyNameFromGetter + ", or " + orString + " if it is not present." + + return wrapToDocumentation(''' + Return «propReturn». + + «reference.formatReference» + @return {@code «method.returnType.fullyQualifiedName»} «propReturn» + ''') + } + + def private generateAccessorMethod(MethodSignature method) { + return ''' + «accessorJavadoc(method, "{@code null}")» + «method.annotations.generateAnnotations» + «method.returnType.nullableType» «method.name»(); + ''' + } def private generateDefaultImplementedInterface() ''' @«OVERRIDE.importedName» @@ -305,7 +319,7 @@ class InterfaceTemplate extends BaseTemplate { def private generateNonnullMethod(MethodSignature method) ''' «val ret = method.returnType» «val name = method.name» - «formatDataForJavaDoc(method, "@return " + asCode(ret.fullyQualifiedName) + " " + asCode(propertyNameFromGetter(method)) + ", or an empty list if it is not present")» + «accessorJavadoc(method, "an empty list")» «method.annotations.generateAnnotations» default «ret.importedNonNull» «name»() { return «CODEHELPERS.importedName».nonnull(«name.getGetterMethodForNonnull»()); diff --git a/binding/mdsal-binding-java-api-generator/src/test/java/org/opendaylight/mdsal/binding/java/api/generator/test/Bug5151Test.java b/binding/mdsal-binding-java-api-generator/src/test/java/org/opendaylight/mdsal/binding/java/api/generator/test/Bug5151Test.java index d1f62d3eda..750780a3f9 100644 --- a/binding/mdsal-binding-java-api-generator/src/test/java/org/opendaylight/mdsal/binding/java/api/generator/test/Bug5151Test.java +++ b/binding/mdsal-binding-java-api-generator/src/test/java/org/opendaylight/mdsal/binding/java/api/generator/test/Bug5151Test.java @@ -37,12 +37,12 @@ public class Bug5151Test extends BaseCompilationTest { final File fooContainerFile = generatedFiles.get("FooContainer.java"); assertNotNull(fooContainerFile); FileSearchUtil.assertFileContains(fooContainerFile, - "@return java.lang.String fooInContainer, or null if not present"); + "@return {@code java.lang.String} fooInContainer, or {@code null} if it is not present"); final File fooDataFile = generatedFiles.get("FooData.java"); assertNotNull(fooDataFile); FileSearchUtil.assertFileContains(fooDataFile, - "FooContainer fooContainer, or null if not present"); + "FooContainer} fooContainer, or {@code null} if it is not present"); CompilationTestUtils.cleanUp(sourcesOutputDir, compiledOutputDir); }