binding/mdsal-binding-generator-api/src/main/java/org/opendaylight/mdsal/binding/model/api/TypeMemberComment.java

   1 /*
   2  * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.mdsal.binding.model.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  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;
  18
  19 /**
  20  * Structured comment of a particular class member. This is aimed towards unifying the layout of a particular type.
  21  */
  22 @Beta
  23 public final class TypeMemberComment implements Immutable {
  24     private final String contractDescription;
  25     private final String referenceDescription;
  26     private final String typeSignature;
  27
  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;
  33     }
  34
  35     /**
  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:
  38      * <ul>
  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>
  42      * </ul>
  43      *
  44      * @return The equivalent of the above blurb.
  45      */
  46     public @Nullable String contractDescription() {
  47         return contractDescription;
  48     }
  49
  50     /**
  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:
  53      *
  54      * <p>
  55      * <pre>
  56      *   <code>
  57      *     A 32-bit bit unsigned word. Individual bits are expected to be interpreted as follows:
  58      *
  59      *       31
  60      *     +----+ ...
  61      *   </code>
  62      * </pre>
  63      *
  64      * @return The equivalent of the above pre-formmated paragraph.
  65      */
  66     public @Nullable String referenceDescription() {
  67         return referenceDescription;
  68     }
  69
  70     /**
  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>
  74      *
  75      * @return Return the signature description, just like these words right here
  76      */
  77     public @Nullable String typeSignature() {
  78         return typeSignature;
  79     }
  80
  81     public static @NonNull TypeMemberComment contractOf(final String contractDescription) {
  82         return new TypeMemberComment(requireNonNull(contractDescription), null, null);
  83     }
  84
  85     public static @NonNull TypeMemberComment referenceOf(final String referenceDescription) {
  86         return new TypeMemberComment(null, requireNonNull(referenceDescription), null);
  87     }
  88
  89     @Override
  90     public int hashCode() {
  91         return Objects.hash(contractDescription, referenceDescription, typeSignature);
  92     }
  93
  94     @Override
  95     public boolean equals(final Object obj) {
  96         if (obj == this) {
  97             return true;
  98         }
  99         if (!(obj instanceof TypeMemberComment)) {
 100             return false;
 101         }
 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);
 106     }
 107
 108     @Override
 109     public String toString() {
 110         return MoreObjects.toStringHelper(this).omitNullValues()
 111             .add("contract", contractDescription).add("reference", referenceDescription).add("type", typeSignature)
 112             .toString();
 113     }
 114 }