1 /*
   2  * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.javadoc.internal.doclets.toolkit.taglets;
  27 
  28 import java.util.EnumSet;
  29 import java.util.List;
  30 
  31 import javax.lang.model.element.Element;
  32 import javax.lang.model.element.VariableElement;
  33 import javax.lang.model.type.TypeMirror;
  34 
  35 import com.sun.source.doctree.DocTree;
  36 import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
  37 import jdk.javadoc.internal.doclets.toolkit.Content;
  38 import jdk.javadoc.internal.doclets.toolkit.taglets.Taglet.UnsupportedTagletOperationException;
  39 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
  40 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  41 
  42 /**
  43  * The interface for the taglet writer.
  44  *
  45  *  <p><b>This is NOT part of any supported API.
  46  *  If you write code that depends on this, you do so at your own risk.
  47  *  This code and its internal interfaces are subject to change or
  48  *  deletion without notice.</b>
  49  *
  50  * @author Jamie Ho
  51  */
  52 
  53 public abstract class TagletWriter {
  54 
  55     /**
  56      * True if we only want to write the first sentence.
  57      */
  58     protected final boolean isFirstSentence;
  59 
  60     protected TagletWriter(boolean isFirstSentence) {
  61         this.isFirstSentence = isFirstSentence;
  62     }
  63 
  64     /**
  65      * @return an instance of an output object.
  66      */
  67     public abstract Content getOutputInstance();
  68 
  69     /**
  70      * Return the output for a {@code {@code ...}} tag.
  71      *
  72      * @param element
  73      * @param tag the tag.
  74      * @return the output of the taglet.
  75      */
  76     protected abstract Content codeTagOutput(Element element, DocTree tag);
  77 
  78     /**
  79      * Return the output for a {@index...} tag.
  80      *
  81      * @param tag the tag.
  82      * @return the output of the taglet.
  83      */
  84     protected abstract Content indexTagOutput(Element element, DocTree tag);
  85 
  86     /**
  87      * Returns the output for the DocRoot inline tag.
  88      * @return the output for the DocRoot inline tag.
  89      */
  90     protected abstract Content getDocRootOutput();
  91 
  92     /**
  93      * Return the deprecated tag output.
  94      *
  95      * @param element the element to write deprecated documentation for.
  96      * @return the output of the deprecated tag.
  97      */
  98     protected abstract Content deprecatedTagOutput(Element element);
  99 
 100     /**
 101      * Return the output for a {@code {@literal ...}} tag.
 102      *
 103      * @param element
 104      * @param tag the tag.
 105      * @return the output of the taglet.
 106      */
 107     protected abstract Content literalTagOutput(Element element, DocTree tag);
 108 
 109     /**
 110      * Return the header for the param tags.
 111      *
 112      * @param header the header to display.
 113      * @return the header for the param tags.
 114      */
 115     protected abstract Content getParamHeader(String header);
 116 
 117     /**
 118      * Return the output for param tags.
 119      *
 120      * @param element
 121      * @param paramTag the parameter to document.
 122      * @param paramName the name of the parameter.
 123      * @return the output of the param tag.
 124      */
 125     protected abstract Content paramTagOutput(Element element, DocTree paramTag, String paramName);
 126 
 127     /**
 128      * Return the output for property tags.
 129      *
 130      * @param element
 131      * @param propertyTag the parameter to document.
 132      * @param prefix the text with which to prefix the property name.
 133      * @return the output of the param tag.
 134      */
 135     protected abstract Content propertyTagOutput(Element element, DocTree propertyTag, String prefix);
 136 
 137     /**
 138      * Return the return tag output.
 139      *
 140      * @param element
 141      * @param returnTag the return tag to output.
 142      * @return the output of the return tag.
 143      */
 144     protected abstract Content returnTagOutput(Element element, DocTree returnTag);
 145 
 146     /**
 147      * Return the see tag output.
 148      *
 149      * @param holder
 150      * @param seeTags the array of See tags.
 151      * @return the output of the see tags.
 152      */
 153     protected abstract Content seeTagOutput(Element holder, List<? extends DocTree> seeTags);
 154 
 155     /**
 156      * Return the accessor tag output.
 157      *
 158      * @param holder
 159      * @param tags the accessor tags
 160      * @return the output of the accessor tag.
 161      */
 162     protected abstract Content accessorTagOutput(Element holder, List<? extends DocTree> tags);
 163 
 164     /**
 165      * Return the output for a simple tag.
 166      *
 167      * @param element
 168      * @param simpleTags the array of simple tags.
 169      * @param header
 170      * @return the output of the simple tags.
 171      */
 172     protected abstract Content simpleTagOutput(Element element, List<? extends DocTree> simpleTags, String header);
 173 
 174     /**
 175      * Return the output for a simple tag.
 176      *
 177      * @param element
 178      * @param simpleTag the simple tag.
 179      * @param header
 180      * @return the output of the simple tag.
 181      */
 182     protected abstract Content simpleTagOutput(Element element, DocTree simpleTag, String header);
 183 
 184     /**
 185      * Return the system property tag output.
 186      *
 187      * @param element
 188      * @param systemPropertyTag the system property tag
 189      * @return the output of system property tag
 190      */
 191     protected abstract Content systemPropertyTagOutput(Element element, DocTree systemPropertyTag);
 192 
 193     /**
 194      * Return the header for the throws tag.
 195      *
 196      * @return the header for the throws tag.
 197      */
 198     protected abstract Content getThrowsHeader();
 199 
 200     /**
 201      * Return the header for the throws tag.
 202      *
 203      * @param element
 204      * @param throwsTag the throws tag.
 205      * @return the output of the throws tag.
 206      */
 207     protected abstract Content throwsTagOutput(Element element, DocTree throwsTag);
 208 
 209     /**
 210      * Return the output for the throws tag.
 211      *
 212      * @param throwsType the throws type.
 213      * @return the output of the throws type.
 214      */
 215     protected abstract Content throwsTagOutput(TypeMirror throwsType);
 216 
 217     /**
 218      * Return the output for the value tag.
 219      *
 220      * @param field       the constant field that holds the value tag.
 221      * @param constantVal the constant value to document.
 222      * @param includeLink true if we should link the constant text to the
 223      *                    constant field itself.
 224      * @return the output of the value tag.
 225      */
 226     protected abstract Content valueTagOutput(VariableElement field,
 227         String constantVal, boolean includeLink);
 228 
 229     /**
 230      * Given an output object, append to it the tag documentation for
 231      * the given member.
 232      *
 233      * @param tagletManager the manager that manages the taglets.
 234      * @param element the Doc that we are print tags for.
 235      * @param taglets the taglets to print.
 236      * @param writer the writer that will generate the output strings.
 237      * @param output the output buffer to store the output in.
 238      */
 239     public static void genTagOutput(TagletManager tagletManager, Element element,
 240             List<Taglet> taglets, TagletWriter writer, Content output) {
 241         Utils utils = writer.configuration().utils;
 242         tagletManager.checkTags(element, utils.getBlockTags(element), false);
 243         tagletManager.checkTags(element, utils.getFullBody(element), true);
 244         for (Taglet taglet : taglets) {
 245             if (utils.isTypeElement(element) && taglet instanceof ParamTaglet) {
 246                 //The type parameters are documented in a special section away
 247                 //from the tag info, so skip here.
 248                 continue;
 249             }
 250             if (taglet instanceof DeprecatedTaglet) {
 251                 //Deprecated information is documented "inline", not in tag info
 252                 //section.
 253                 continue;
 254             }
 255             if (taglet instanceof SimpleTaglet && !((SimpleTaglet) taglet).enabled) {
 256                 // taglet has been disabled
 257                 continue;
 258             }
 259             Content currentOutput = null;
 260             try {
 261                 currentOutput = taglet.getTagletOutput(element, writer);
 262             } catch (UnsupportedTagletOperationException utoe) {
 263                 //The taglet does not take a member as an argument.  Let's try
 264                 //a single tag.
 265                 List<? extends DocTree> tags = utils.getBlockTags(element, taglet.getName());
 266                 if (!tags.isEmpty()) {
 267                     currentOutput = taglet.getTagletOutput(element, tags.get(0), writer);
 268                 }
 269             }
 270             if (currentOutput != null) {
 271                 tagletManager.seenCustomTag(taglet.getName());
 272                 output.add(currentOutput);
 273             }
 274         }
 275     }
 276     /**
 277      * Given an inline tag, return its output.
 278      * @param holder
 279      * @param tagletManager The taglet manager for the current doclet.
 280      * @param holderTag The tag this holds this inline tag.  Null if there
 281      * is no tag that holds it.
 282      * @param inlineTag The inline tag to be documented.
 283      * @param tagletWriter The taglet writer to write the output.
 284      * @return The output of the inline tag.
 285      */
 286     public static Content getInlineTagOutput(Element holder, TagletManager tagletManager,
 287             DocTree holderTag, DocTree inlineTag, TagletWriter tagletWriter) {
 288         List<Taglet> definedTags = tagletManager.getInlineTaglets();
 289         CommentHelper ch = tagletWriter.configuration().utils.getCommentHelper(holder);
 290         final String inlineTagName = ch.getTagName(inlineTag);
 291         //This is a custom inline tag.
 292         for (Taglet definedTag : definedTags) {
 293             if ((definedTag.getName()).equals(inlineTagName)) {
 294                 // Given a name of a seen custom tag, remove it from the
 295                 // set of unseen custom tags.
 296                 tagletManager.seenCustomTag(definedTag.getName());
 297                 Content output = definedTag.getTagletOutput(holder,
 298                         holderTag != null &&
 299                         definedTag.getName().equals("inheritDoc") ?
 300                         holderTag : inlineTag, tagletWriter);
 301                 return output;
 302             }
 303         }
 304         return null;
 305     }
 306 
 307     /**
 308      * Converts inline tags and text to TagOutput, expanding the
 309      * inline tags along the way.  Called wherever text can contain
 310      * an inline tag, such as in comments or in free-form text arguments
 311      * to non-inline tags.
 312      *
 313      * @param holderTag the tag that holds the documentation.
 314      * @param tags   array of text tags and inline tags (often alternating)
 315      *               present in the text of interest for this doc.
 316      * @return the {@link Content} representing the comments.
 317      */
 318     public abstract Content commentTagsToOutput(DocTree holderTag, List<? extends DocTree> tags);
 319 
 320     /**
 321      * Converts inline tags and text to TagOutput, expanding the
 322      * inline tags along the way.  Called wherever text can contain
 323      * an inline tag, such as in comments or in free-form text arguments
 324      * to non-inline tags.
 325      *
 326      * @param holder the element where comment resides.
 327      * @param tags   array of text tags and inline tags (often alternating)
 328      *               present in the text of interest for this doc.
 329      * @return the {@link Content} representing the comments.
 330      */
 331     public abstract Content commentTagsToOutput(Element holder, List<? extends DocTree> tags);
 332 
 333     /**
 334      * Converts inline tags and text to TagOutput, expanding the
 335      * inline tags along the way.  Called wherever text can contain
 336      * an inline tag, such as in comments or in free-form text arguments
 337      * to non-inline tags.
 338      *
 339      * @param holderTag the tag that holds the documentation.
 340      * @param holder the element where comment resides.
 341      * @param tags   array of text tags and inline tags (often alternating)
 342      *               present in the text of interest for this doc.
 343      * @param isFirstSentence true if this is the first sentence.
 344      * @return the {@link Content} representing the comments.
 345      */
 346     public abstract Content commentTagsToOutput(DocTree holderTag,
 347         Element holder, List<? extends DocTree> tags, boolean isFirstSentence);
 348 
 349     /**
 350      * @return an instance of the configuration used for this doclet.
 351      */
 352     public abstract BaseConfiguration configuration();
 353 }