2 * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.mdsal.binding.model.api;
10 import static java.util.Objects.requireNonNull;
12 import com.google.common.annotations.Beta;
13 import com.google.common.base.MoreObjects;
14 import java.util.Objects;
15 import org.eclipse.jdt.annotation.NonNull;
16 import org.eclipse.jdt.annotation.Nullable;
17 import org.opendaylight.yangtools.concepts.Immutable;
20 * Structured comment of a particular class member. This is aimed towards unifying the layout of a particular type.
23 public final class TypeMemberComment implements Immutable {
24 private final String contractDescription;
25 private final String referenceDescription;
26 private final String typeSignature;
28 public TypeMemberComment(final String contractDescription, final String referenceDescription,
29 final String typeSignature) {
30 this.contractDescription = contractDescription;
31 this.referenceDescription = referenceDescription;
32 this.typeSignature = typeSignature;
36 * Return the member contract description. This string, if present will represent the equivalent of the words you
37 * are just reading. This forms what is usually:
39 * <li>hand-written with careful explanation</li>
40 * <li>describing the general contract outline, what the member does/holds/etc. For methods this might be pre-
41 * and post-conditions.</li>
44 * @return The equivalent of the above blurb.
46 public @Nullable String contractDescription() {
47 return contractDescription;
51 * Return the member reference description. This description is passed unmodified, pre-formatted in a single block.
52 * It is expected to look something like the following paragraph:
57 * A 32-bit bit unsigned word. Individual bits are expected to be interpreted as follows:
64 * @return The equivalent of the above pre-formmated paragraph.
66 public @Nullable String referenceDescription() {
67 return referenceDescription;
71 * Return the type signature of this type member. This is only applicable for methods, use of anywhere else is
72 * expected to either be ignored, or processed as is. As a matter of example, this method has a signature starting
73 * right after this period<b>.</b>
75 * @return Return the signature description, just like these words right here
77 public @Nullable String typeSignature() {
81 public static @NonNull TypeMemberComment contractOf(final String contractDescription) {
82 return new TypeMemberComment(requireNonNull(contractDescription), null, null);
85 public static @NonNull TypeMemberComment referenceOf(final String referenceDescription) {
86 return new TypeMemberComment(null, requireNonNull(referenceDescription), null);
90 public int hashCode() {
91 return Objects.hash(contractDescription, referenceDescription, typeSignature);
95 public boolean equals(final Object obj) {
99 if (!(obj instanceof TypeMemberComment)) {
102 final TypeMemberComment other = (TypeMemberComment) obj;
103 return Objects.equals(contractDescription, other.contractDescription)
104 && Objects.equals(referenceDescription, other.referenceDescription)
105 && Objects.equals(typeSignature, other.typeSignature);
109 public String toString() {
110 return MoreObjects.toStringHelper(this).omitNullValues()
111 .add("contract", contractDescription).add("reference", referenceDescription).add("type", typeSignature)