binding/binding-model/src/main/java/org/opendaylight/yangtools/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.yangtools.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:
  53      * <pre>
  54      *   <code>
  55      *     A 32-bit bit unsigned word. Individual bits are expected to be interpreted as follows:
  56      *
  57      *       31
  58      *     +----+ ...
  59      *   </code>
  60      * </pre>
  61      *
  62      * @return The equivalent of the above pre-formmated paragraph.
  63      */
  64     public @Nullable String referenceDescription() {
  65         return referenceDescription;
  66     }
  67
  68     /**
  69      * Return the type signature of this type member. This is only applicable for methods, use of anywhere else is
  70      * expected to either be ignored, or processed as is. As a matter of example, this method has a signature starting
  71      * right after this period<b>.</b>
  72      *
  73      * @return Return the signature description, just like these words right here
  74      */
  75     public @Nullable String typeSignature() {
  76         return typeSignature;
  77     }
  78
  79     public static @NonNull TypeMemberComment contractOf(final String contractDescription) {
  80         return new TypeMemberComment(requireNonNull(contractDescription), null, null);
  81     }
  82
  83     public static @NonNull TypeMemberComment referenceOf(final String referenceDescription) {
  84         return new TypeMemberComment(null, requireNonNull(referenceDescription), null);
  85     }
  86
  87     @Override
  88     public int hashCode() {
  89         return Objects.hash(contractDescription, referenceDescription, typeSignature);
  90     }
  91
  92     @Override
  93     public boolean equals(final Object obj) {
  94         return obj == this || obj instanceof TypeMemberComment other
  95             && Objects.equals(contractDescription, other.contractDescription)
  96             && Objects.equals(referenceDescription, other.referenceDescription)
  97             && Objects.equals(typeSignature, other.typeSignature);
  98     }
  99
 100     @Override
 101     public String toString() {
 102         return MoreObjects.toStringHelper(this).omitNullValues()
 103             .add("contract", contractDescription).add("reference", referenceDescription).add("type", typeSignature)
 104             .toString();
 105     }
 106 }