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.
* @return the Type that declares member.
*/
Type getDefiningType();
-
}
--- /dev/null
+/*
+ * 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:
+ * <ul>
+ * <li>hand-written with careful explanation</li>
+ * <li>describing the general contract outline, what the member does/holds/etc. For methods this might be pre-
+ * and post-conditions.</li>
+ * </ul>
+ *
+ * @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:
+ *
+ * <p>
+ * <pre>
+ * <code>
+ * A 32-bit bit unsigned word. Individual bits are expected to be interpreted as follows:
+ *
+ * 31
+ * +----+ ...
+ * </code>
+ * </pre>
+ *
+ * @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<b>.</b>
+ *
+ * @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();
+ }
+}
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
* addName due to enforce reason that MethodSignatureBuilder SHOULD be
* instantiated only once with defined method name. <br>
* 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
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<T extends TypeMemberBuilder<T>> extends AnnotableTypeBuilder {
/**
* 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
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);
// 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(
*/
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;
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 {
@Override
void addComment(final TypeMemberBuilder<?> genType, final DocumentedNode node) {
- final Optional<String> 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 + '}'));
}
}
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 {
void addComment(final TypeMemberBuilder<?> genType, final DocumentedNode node) {
// No-op
}
+
+ @Override
+ void addRpcMethodComment(final TypeMemberBuilder<?> genType, final RpcDefinition node) {
+ // No-op
+ }
}
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<AnnotationType> annotations;
private final AccessModifier accessModifier;
protected AbstractTypeMember(final Type definingType, final String name, final List<AnnotationType> 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;
}
@Override
- public String getComment() {
- return this.comment;
+ public TypeMemberComment getComment() {
+ return comment;
}
@Override
@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
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;
@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();
}
}
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;
private final String name;
private Type returnType;
private List<AnnotationTypeBuilder> annotationBuilders = Collections.emptyList();
- private String comment = "";
+ private TypeMemberComment comment;
private boolean isFinal;
private boolean isStatic;
private AccessModifier accessModifier;
return this.annotationBuilders;
}
- protected String getComment() {
+ protected TypeMemberComment getComment() {
return this.comment;
}
}
@Override
- public T setComment(final String newComment) {
+ public T setComment(final TypeMemberComment newComment) {
this.comment = newComment;
return thisInstance();
}
@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
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<AnnotationType> 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;
@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();
}
}
final class MethodSignatureBuilderImpl extends AbstractTypeMemberBuilder<MethodSignatureBuilder>
implements MethodSignatureBuilder {
-
private List<MethodSignature.Parameter> parameters = Collections.emptyList();
private List<MethodSignature.Parameter> unmodifiableParams = Collections.emptyList();
private ValueMechanics mechanics = ValueMechanics.NORMAL;
@Override
public int hashCode() {
- final int prime = 31;
- int result = 1;
- result = prime * result + Objects.hashCode(getName());
- result = prime * result + Objects.hashCode(this.parameters);
- result = prime * result + Objects.hashCode(getReturnType());
- return result;
+ return Objects.hash(getName(), parameters, getReturnType());
}
@Override
import org.opendaylight.mdsal.binding.model.api.AnnotationType;
import org.opendaylight.mdsal.binding.model.api.MethodSignature;
import org.opendaylight.mdsal.binding.model.api.Type;
+import org.opendaylight.mdsal.binding.model.api.TypeMemberComment;
class MethodSignatureImpl extends AbstractTypeMember implements MethodSignature {
private final List<Parameter> params;
@VisibleForTesting
MethodSignatureImpl(final Type definingType, final String name, final List<AnnotationType> annotations,
- final String comment, final AccessModifier accessModifier, final Type returnType,
+ final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType,
final List<Parameter> 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<AnnotationType> annotations,
- final String comment, final AccessModifier accessModifier, final Type returnType,
+ final TypeMemberComment comment, final AccessModifier accessModifier, final Type returnType,
final List<Parameter> 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);
@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) {
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();
}
}
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 {
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());
assertNotNull(genProperty.toString());
assertTrue(genProperty.equals(genProperty2));
assertFalse(genProperty.equals(null));
-
}
}
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;
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());
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 {
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);
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
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 {
@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());
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;
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 {
Type type = Types.STRING;
String name = "customMethod";
List<AnnotationType> 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<Parameter> params = new ArrayList<>();
@Test
public void testHashCode() {
assertEquals(hash1, hash1);
- assertTrue(!(hash1 == hash4));
+ assertNotEquals(hash1, hash4);
}
@Test
*/
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
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
"_" + 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
* @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) {
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)
}
}
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»
+ <pre>
+ <code>
+ «reference.encodeAngleBrackets.formatToParagraph»
+ </code>
+ </pre>
- def asCode(String text) {
- return "<code>" + text + "</code>"
- }
+ «ENDIF»
+ '''
def asLink(String text) {
val StringBuilder sb = new StringBuilder()
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
isFirstElementOnNewLineEmptyChar = !isFirstElementOnNewLineEmptyChar;
}
}
-
if (isFirstElementOnNewLineEmptyChar) {
isFirstElementOnNewLineEmptyChar = !isFirstElementOnNewLineEmptyChar
} else {
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;
}
@Override
- public String getComment() {
+ public TypeMemberComment getComment() {
throw uoe();
}
* @return string with class source code in JAVA format
*/
def protected generateBody(boolean isInnerClass) '''
- «wrapToDocumentation(formatDataForJavaDoc(type))»
+ «type.formatDataForJavaDoc.wrapToDocumentation»
«annotationDeclaration»
«generateClassDeclaration(isInnerClass)» {
«suidDeclaration»
*/
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
}
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»")
'''
* @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)»
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.
* @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»
«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»
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»());
final File fooContainerFile = generatedFiles.get("FooContainer.java");
assertNotNull(fooContainerFile);
FileSearchUtil.assertFileContains(fooContainerFile,
- "@return <code>java.lang.String</code> <code>fooInContainer</code>, or <code>null</code> 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</code> <code>fooContainer</code>, or <code>null</code> if not present");
+ "FooContainer} fooContainer, or {@code null} if it is not present");
CompilationTestUtils.cleanUp(sourcesOutputDir, compiledOutputDir);
}