/*
 * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package jdk.javadoc.internal.doclets.toolkit.taglets;

import java.util.List;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.TypeMirror;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.taglets.Taglet.UnsupportedTagletOperationException;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

The interface for the taglet writer.
 
This is NOT part of any supported API.
 If you write code that depends on this, you do so at your own risk.
 This code and its internal interfaces are subject to change or
 deletion without notice.
/**
 * The interface for the taglet writer.
 *
 *  <p><b>This is NOT part of any supported API.
 *  If you write code that depends on this, you do so at your own risk.
 *  This code and its internal interfaces are subject to change or
 *  deletion without notice.</b>
 */

public abstract class TagletWriter {

    
True if we only want to write the first sentence.
/**
     * True if we only want to write the first sentence.
     */
    protected final boolean isFirstSentence;

    protected TagletWriter(boolean isFirstSentence) {
        this.isFirstSentence = isFirstSentence;
    }

    
Returns:
an instance of an output object./**
     * @return an instance of an output object.
     */
    public abstract Content getOutputInstance();

    
Return the output for a {@code ...} tag. 
Params:
element – 
tag – the tag.
Returns:
the output of the taglet./**
     * Return the output for a {@code {@code ...}} tag.
     *
     * @param element
     * @param tag the tag.
     * @return the output of the taglet.
     */
    protected abstract Content codeTagOutput(Element element, DocTree tag);

    
Return the output for a {@index...} tag. 
Params:
tag – the tag.
Returns:
the output of the taglet./**
     * Return the output for a {@code {@index...}} tag.
     *
     * @param tag the tag.
     * @return the output of the taglet.
     */
    protected abstract Content indexTagOutput(Element element, DocTree tag);

    
Returns the output for the DocRoot inline tag.
Returns:
the output for the DocRoot inline tag./**
     * Returns the output for the DocRoot inline tag.
     * @return the output for the DocRoot inline tag.
     */
    protected abstract Content getDocRootOutput();

    
Return the deprecated tag output.
Params:
element – the element to write deprecated documentation for.
Returns:
the output of the deprecated tag./**
     * Return the deprecated tag output.
     *
     * @param element the element to write deprecated documentation for.
     * @return the output of the deprecated tag.
     */
    protected abstract Content deprecatedTagOutput(Element element);

    
Return the output for a {@literal ...} tag. 
Params:
element – 
tag – the tag.
Returns:
the output of the taglet./**
     * Return the output for a {@code {@literal ...}} tag.
     *
     * @param element
     * @param tag the tag.
     * @return the output of the taglet.
     */
    protected abstract Content literalTagOutput(Element element, DocTree tag);

    
Return the header for the param tags.
Params:
kind – the kind of header that is required
Returns:
the header for the param tags/**
     * Return the header for the param tags.
     *
     * @param kind the kind of header that is required
     * @return the header for the param tags
     */
    protected abstract Content getParamHeader(ParamTaglet.ParamKind kind);

    
Return the output for param tags.
Params:
element – 
paramTag – the parameter to document.
paramName – the name of the parameter.
Returns:
the output of the param tag./**
     * Return the output for param tags.
     *
     * @param element
     * @param paramTag the parameter to document.
     * @param paramName the name of the parameter.
     * @return the output of the param tag.
     */
    protected abstract Content paramTagOutput(Element element, DocTree paramTag, String paramName);

    
Return the output for property tags.
Params:
element – 
propertyTag – the parameter to document.
prefix – the text with which to prefix the property name.
Returns:
the output of the param tag./**
     * Return the output for property tags.
     *
     * @param element
     * @param propertyTag the parameter to document.
     * @param prefix the text with which to prefix the property name.
     * @return the output of the param tag.
     */
    protected abstract Content propertyTagOutput(Element element, DocTree propertyTag, String prefix);

    
Return the return tag output.
Params:
element – 
returnTag – the return tag to output.
Returns:
the output of the return tag./**
     * Return the return tag output.
     *
     * @param element
     * @param returnTag the return tag to output.
     * @return the output of the return tag.
     */
    protected abstract Content returnTagOutput(Element element, DocTree returnTag);

    
Return the see tag output.
Params:
holder – 
seeTags – the array of See tags.
Returns:
the output of the see tags./**
     * Return the see tag output.
     *
     * @param holder
     * @param seeTags the array of See tags.
     * @return the output of the see tags.
     */
    protected abstract Content seeTagOutput(Element holder, List<? extends DocTree> seeTags);

    
Return the output for a simple tag.
Params:
element – 
simpleTags – the array of simple tags.
header – 
Returns:
the output of the simple tags./**
     * Return the output for a simple tag.
     *
     * @param element
     * @param simpleTags the array of simple tags.
     * @param header
     * @return the output of the simple tags.
     */
    protected abstract Content simpleTagOutput(Element element, List<? extends DocTree> simpleTags, String header);

    
Return the output for a simple tag.
Params:
element – 
simpleTag – the simple tag.
header – 
Returns:
the output of the simple tag./**
     * Return the output for a simple tag.
     *
     * @param element
     * @param simpleTag the simple tag.
     * @param header
     * @return the output of the simple tag.
     */
    protected abstract Content simpleTagOutput(Element element, DocTree simpleTag, String header);

    
Return the system property tag output.
Params:
element – 
systemPropertyTag – the system property tag
Returns:
the output of system property tag/**
     * Return the system property tag output.
     *
     * @param element
     * @param systemPropertyTag the system property tag
     * @return the output of system property tag
     */
    protected abstract Content systemPropertyTagOutput(Element element, DocTree systemPropertyTag);

    
Return the header for the throws tag.
Returns:
the header for the throws tag./**
     * Return the header for the throws tag.
     *
     * @return the header for the throws tag.
     */
    protected abstract Content getThrowsHeader();

    
Return the header for the throws tag.
Params:
element – 
throwsTag – the throws tag.
substituteType – instantiated type of a generic type-variable, or null.
Returns:
the output of the throws tag./**
     * Return the header for the throws tag.
     *
     * @param element
     * @param throwsTag the throws tag.
     * @param substituteType instantiated type of a generic type-variable, or null.
     * @return the output of the throws tag.
     */
    protected abstract Content throwsTagOutput(Element element, DocTree throwsTag, TypeMirror substituteType);

    
Return the output for the throws tag.
Params:
throwsType – the throws type.
Returns:
the output of the throws type./**
     * Return the output for the throws tag.
     *
     * @param throwsType the throws type.
     * @return the output of the throws type.
     */
    protected abstract Content throwsTagOutput(TypeMirror throwsType);

    
Return the output for the value tag.
Params:
field –       the constant field that holds the value tag.
constantVal – the constant value to document.
includeLink – true if we should link the constant text to the
                   constant field itself.
Returns:
the output of the value tag./**
     * Return the output for the value tag.
     *
     * @param field       the constant field that holds the value tag.
     * @param constantVal the constant value to document.
     * @param includeLink true if we should link the constant text to the
     *                    constant field itself.
     * @return the output of the value tag.
     */
    protected abstract Content valueTagOutput(VariableElement field,
        String constantVal, boolean includeLink);

    
Return the main type element of the current page or null for pages that don't have one.
Returns:
the type element of the current page or null./**
     * Return the main type element of the current page or null for pages that don't have one.
     *
     * @return the type element of the current page or null.
     */
    protected abstract TypeElement getCurrentPageElement();

    
Given an output object, append to it the tag documentation for
the given member.
Params:
tagletManager – the manager that manages the taglets.
element – the element that we are print tags for.
taglets – the taglets to print.
writer – the writer that will generate the output strings.
output – the output buffer to store the output in./**
     * Given an output object, append to it the tag documentation for
     * the given member.
     *
     * @param tagletManager the manager that manages the taglets.
     * @param element the element that we are print tags for.
     * @param taglets the taglets to print.
     * @param writer the writer that will generate the output strings.
     * @param output the output buffer to store the output in.
     */
    public static void genTagOutput(TagletManager tagletManager,
                                    Element element,
                                    List<Taglet> taglets,
                                    TagletWriter writer,
                                    Content output)
    {
        Utils utils = writer.configuration().utils;
        tagletManager.checkTags(element, utils.getBlockTags(element), false);
        tagletManager.checkTags(element, utils.getFullBody(element), true);
        for (Taglet taglet : taglets) {
            if (utils.isTypeElement(element) && taglet instanceof ParamTaglet) {
                // The type parameters and state components are documented in a special
                // section away from the tag info, so skip here.
                continue;
            }
            if (element.getKind() == ElementKind.MODULE && taglet instanceof BaseTaglet) {
                BaseTaglet t = (BaseTaglet) taglet;
                switch (t.getTagKind()) {
                    // @uses and @provides are handled separately, so skip here.
                    // See ModuleWriterImpl.computeModulesData
                    case USES:
                    case PROVIDES:
                        continue;
                }
            }
            if (taglet instanceof DeprecatedTaglet) {
                //Deprecated information is documented "inline", not in tag info
                //section.
                continue;
            }
            if (taglet instanceof SimpleTaglet && !((SimpleTaglet) taglet).enabled) {
                // taglet has been disabled
                continue;
            }
            Content currentOutput = null;
            try {
                currentOutput = taglet.getTagletOutput(element, writer);
            } catch (UnsupportedTagletOperationException utoe) {
                //The taglet does not take a member as an argument.  Let's try
                //a single tag.
                List<? extends DocTree> tags = utils.getBlockTags(element, taglet);
                if (!tags.isEmpty()) {
                    currentOutput = taglet.getTagletOutput(element, tags.get(0), writer);
                }
            }
            if (currentOutput != null) {
                tagletManager.seenCustomTag(taglet.getName());
                output.add(currentOutput);
            }
        }
    }
    
Given an inline tag, return its output.
Params:
holder – 
tagletManager – The taglet manager for the current doclet.
holderTag – The tag that holds this inline tag, or null if there is no tag that holds it.
inlineTag – The inline tag to be documented.
tagletWriter – The taglet writer to write the output.
Returns:
The output of the inline tag./**
     * Given an inline tag, return its output.
     * @param holder
     * @param tagletManager The taglet manager for the current doclet.
     * @param holderTag The tag that holds this inline tag, or {@code null} if
     *                  there is no tag that holds it.
     * @param inlineTag The inline tag to be documented.
     * @param tagletWriter The taglet writer to write the output.
     * @return The output of the inline tag.
     */
    public static Content getInlineTagOutput(Element holder,
                                             TagletManager tagletManager,
                                             DocTree holderTag,
                                             DocTree inlineTag,
                                             TagletWriter tagletWriter)
    {
        List<Taglet> definedTags = tagletManager.getInlineTaglets();
        CommentHelper ch = tagletWriter.configuration().utils.getCommentHelper(holder);
        final String inlineTagName = ch.getTagName(inlineTag);
        //This is a custom inline tag.
        for (Taglet definedTag : definedTags) {
            if ((definedTag.getName()).equals(inlineTagName)) {
                // Given a name of a seen custom tag, remove it from the
                // set of unseen custom tags.
                tagletManager.seenCustomTag(definedTag.getName());
                Content output = definedTag.getTagletOutput(holder,
                        holderTag != null &&
                        definedTag.getName().equals("inheritDoc") ?
                        holderTag : inlineTag, tagletWriter);
                return output;
            }
        }
        return null;
    }

    
Converts inline tags and text to TagOutput, expanding the
inline tags along the way.  Called wherever text can contain
an inline tag, such as in comments or in free-form text arguments
to non-inline tags.
Params:
holderTag – the tag that holds the documentation.
tags –   array of text tags and inline tags (often alternating)
              present in the text of interest for this doc.
Returns:
the Content representing the comments./**
     * Converts inline tags and text to TagOutput, expanding the
     * inline tags along the way.  Called wherever text can contain
     * an inline tag, such as in comments or in free-form text arguments
     * to non-inline tags.
     *
     * @param holderTag the tag that holds the documentation.
     * @param tags   array of text tags and inline tags (often alternating)
     *               present in the text of interest for this doc.
     * @return the {@link Content} representing the comments.
     */
    public abstract Content commentTagsToOutput(DocTree holderTag, List<? extends DocTree> tags);

    
Converts inline tags and text to TagOutput, expanding the
inline tags along the way.  Called wherever text can contain
an inline tag, such as in comments or in free-form text arguments
to non-inline tags.
Params:
holder – the element where comment resides.
tags –   array of text tags and inline tags (often alternating)
              present in the text of interest for this doc.
Returns:
the Content representing the comments./**
     * Converts inline tags and text to TagOutput, expanding the
     * inline tags along the way.  Called wherever text can contain
     * an inline tag, such as in comments or in free-form text arguments
     * to non-inline tags.
     *
     * @param holder the element where comment resides.
     * @param tags   array of text tags and inline tags (often alternating)
     *               present in the text of interest for this doc.
     * @return the {@link Content} representing the comments.
     */
    public abstract Content commentTagsToOutput(Element holder, List<? extends DocTree> tags);

    
Converts inline tags and text to TagOutput, expanding the
inline tags along the way.  Called wherever text can contain
an inline tag, such as in comments or in free-form text arguments
to non-inline tags.
Params:
holderTag – the tag that holds the documentation.
holder – the element where comment resides.
tags –   array of text tags and inline tags (often alternating)
              present in the text of interest for this doc.
isFirstSentence – true if this is the first sentence.
Returns:
the Content representing the comments./**
     * Converts inline tags and text to TagOutput, expanding the
     * inline tags along the way.  Called wherever text can contain
     * an inline tag, such as in comments or in free-form text arguments
     * to non-inline tags.
     *
     * @param holderTag the tag that holds the documentation.
     * @param holder the element where comment resides.
     * @param tags   array of text tags and inline tags (often alternating)
     *               present in the text of interest for this doc.
     * @param isFirstSentence true if this is the first sentence.
     * @return the {@link Content} representing the comments.
     */
    public abstract Content commentTagsToOutput(DocTree holderTag,
        Element holder, List<? extends DocTree> tags, boolean isFirstSentence);

    
Returns:
an instance of the configuration used for this doclet./**
     * @return an instance of the configuration used for this doclet.
     */
    public abstract BaseConfiguration configuration();
}