binding/mdsal-binding-generator-util/src/main/java/org/opendaylight/mdsal/binding/model/util/TypeComments.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, 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.util;
   9
  10 import static org.opendaylight.mdsal.binding.model.util.BindingGeneratorUtil.replaceAllIllegalChars;
  11 import static org.opendaylight.mdsal.binding.model.util.FormattingUtils.formatToParagraph;
  12
  13 import com.google.common.annotations.Beta;
  14 import com.google.common.escape.Escaper;
  15 import com.google.common.escape.Escapers;
  16 import java.util.Optional;
  17 import java.util.regex.Pattern;
  18 import org.eclipse.jdt.annotation.NonNullByDefault;
  19 import org.opendaylight.mdsal.binding.model.api.TypeComment;
  20 import org.opendaylight.yangtools.yang.model.api.DocumentedNode;
  21
  22 /**
  23  * Utility methods for creating {@link TypeComment}s.
  24  */
  25 @Beta
  26 @NonNullByDefault
  27 public final class TypeComments {
  28     private static final Escaper ENTITY_ESCAPER = Escapers.builder()
  29             .addEscape('<', "&lt;")
  30             .addEscape('>', "&gt;")
  31             .addEscape('&', "&amp;")
  32             .addEscape('@', "&#64;").build();
  33     private static final Pattern TAIL_COMMENT_PATTERN = Pattern.compile("*/", Pattern.LITERAL);
  34
  35     private TypeComments() {
  36
  37     }
  38
  39     /**
  40      * Create a {@link TypeComment} for a javadoc-compliant text snippet. This snippet must be eligible for direct
  41      * inclusion in a Java comment without further escaping.
  42      *
  43      * @param javadoc Pre-formatted javadoc snippet
  44      * @return {@link TypeComment}, or empty if the snippet was empty
  45      */
  46     public static Optional<TypeComment> javadoc(final String javadoc) {
  47         return javadoc.isEmpty() ? Optional.empty() : Optional.of(() -> javadoc);
  48     }
  49
  50     /**
  51      * Create a {@link TypeComment} for a {@link DocumentedNode}'s description string.
  52      *
  53      * @param node Documented node containing the description to be processed
  54      * @return {@link TypeComment}, or empty if the node's description was empty or non-present.
  55      */
  56     public static Optional<TypeComment> description(final DocumentedNode node) {
  57         final String description = node.getDescription().orElse("");
  58         return description.isEmpty() ? Optional.empty() : Optional.of(() -> replaceAllIllegalChars(
  59             formatToParagraph(
  60                 TAIL_COMMENT_PATTERN.matcher(ENTITY_ESCAPER.escape(description)).replaceAll("&#42;&#47;"), 0)));
  61     }
  62 }