1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletWriter.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,310 @@
1.4 +/*
1.5 + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.internal.toolkit.taglets;
1.30 +
1.31 +import com.sun.javadoc.*;
1.32 +import com.sun.tools.doclets.internal.toolkit.*;
1.33 +import com.sun.tools.doclets.internal.toolkit.util.*;
1.34 +
1.35 +/**
1.36 + * The interface for the taglet writer.
1.37 + *
1.38 + * <p><b>This is NOT part of any supported API.
1.39 + * If you write code that depends on this, you do so at your own risk.
1.40 + * This code and its internal interfaces are subject to change or
1.41 + * deletion without notice.</b>
1.42 + *
1.43 + * @since 1.5
1.44 + * @author Jamie Ho
1.45 + */
1.46 +
1.47 +public abstract class TagletWriter {
1.48 +
1.49 + /**
1.50 + * True if we only want to write the first sentence.
1.51 + */
1.52 + protected final boolean isFirstSentence;
1.53 +
1.54 + protected TagletWriter(boolean isFirstSentence) {
1.55 + this.isFirstSentence = isFirstSentence;
1.56 + }
1.57 +
1.58 + /**
1.59 + * @return an instance of an output object.
1.60 + */
1.61 + public abstract Content getOutputInstance();
1.62 +
1.63 + /**
1.64 + * Return the output for a {@code...} tag.
1.65 + *
1.66 + * @param tag the tag.
1.67 + * @return the output of the taglet.
1.68 + */
1.69 + protected abstract Content codeTagOutput(Tag tag);
1.70 +
1.71 + /**
1.72 + * Returns the output for the DocRoot inline tag.
1.73 + * @return the output for the DocRoot inline tag.
1.74 + */
1.75 + protected abstract Content getDocRootOutput();
1.76 +
1.77 + /**
1.78 + * Return the deprecated tag output.
1.79 + *
1.80 + * @param doc the doc to write deprecated documentation for.
1.81 + * @return the output of the deprecated tag.
1.82 + */
1.83 + protected abstract Content deprecatedTagOutput(Doc doc);
1.84 +
1.85 + /**
1.86 + * Return the output for a {@literal...} tag.
1.87 + *
1.88 + * @param tag the tag.
1.89 + * @return the output of the taglet.
1.90 + */
1.91 + protected abstract Content literalTagOutput(Tag tag);
1.92 +
1.93 + /**
1.94 + * Returns {@link MessageRetriever} for output purposes.
1.95 + *
1.96 + * @return {@link MessageRetriever} for output purposes.
1.97 + */
1.98 + protected abstract MessageRetriever getMsgRetriever();
1.99 +
1.100 + /**
1.101 + * Return the header for the param tags.
1.102 + *
1.103 + * @param header the header to display.
1.104 + * @return the header for the param tags.
1.105 + */
1.106 + protected abstract Content getParamHeader(String header);
1.107 +
1.108 + /**
1.109 + * Return the output for param tags.
1.110 + *
1.111 + * @param paramTag the parameter to document.
1.112 + * @param paramName the name of the parameter.
1.113 + * @return the output of the param tag.
1.114 + */
1.115 + protected abstract Content paramTagOutput(ParamTag paramTag,
1.116 + String paramName);
1.117 +
1.118 + /**
1.119 + * Return the output for property tags.
1.120 + *
1.121 + * @param propertyTag the parameter to document.
1.122 + * @param prefix the text with which to prefix the property name.
1.123 + * @return the output of the param tag.
1.124 + */
1.125 + protected abstract Content propertyTagOutput(Tag propertyTag, String prefix);
1.126 +
1.127 + /**
1.128 + * Return the return tag output.
1.129 + *
1.130 + * @param returnTag the return tag to output.
1.131 + * @return the output of the return tag.
1.132 + */
1.133 + protected abstract Content returnTagOutput(Tag returnTag);
1.134 +
1.135 + /**
1.136 + * Return the see tag output.
1.137 + *
1.138 + * @param seeTags the array of See tags.
1.139 + * @return the output of the see tags.
1.140 + */
1.141 + protected abstract Content seeTagOutput(Doc holder, SeeTag[] seeTags);
1.142 +
1.143 + /**
1.144 + * Return the output for a simple tag.
1.145 + *
1.146 + * @param simpleTags the array of simple tags.
1.147 + * @return the output of the simple tags.
1.148 + */
1.149 + protected abstract Content simpleTagOutput(Tag[] simpleTags,
1.150 + String header);
1.151 +
1.152 + /**
1.153 + * Return the output for a simple tag.
1.154 + *
1.155 + * @param simpleTag the simple tag.
1.156 + * @return the output of the simple tag.
1.157 + */
1.158 + protected abstract Content simpleTagOutput(Tag simpleTag, String header);
1.159 +
1.160 + /**
1.161 + * Return the header for the throws tag.
1.162 + *
1.163 + * @return the header for the throws tag.
1.164 + */
1.165 + protected abstract Content getThrowsHeader();
1.166 +
1.167 + /**
1.168 + * Return the header for the throws tag.
1.169 + *
1.170 + * @param throwsTag the throws tag.
1.171 + * @return the output of the throws tag.
1.172 + */
1.173 + protected abstract Content throwsTagOutput(ThrowsTag throwsTag);
1.174 +
1.175 + /**
1.176 + * Return the output for the throws tag.
1.177 + *
1.178 + * @param throwsType the throws type.
1.179 + * @return the output of the throws type.
1.180 + */
1.181 + protected abstract Content throwsTagOutput(Type throwsType);
1.182 +
1.183 + /**
1.184 + * Return the output for the value tag.
1.185 + *
1.186 + * @param field the constant field that holds the value tag.
1.187 + * @param constantVal the constant value to document.
1.188 + * @param includeLink true if we should link the constant text to the
1.189 + * constant field itself.
1.190 + * @return the output of the value tag.
1.191 + */
1.192 + protected abstract Content valueTagOutput(FieldDoc field,
1.193 + String constantVal, boolean includeLink);
1.194 +
1.195 + /**
1.196 + * Given an output object, append to it the tag documentation for
1.197 + * the given member.
1.198 + *
1.199 + * @param tagletManager the manager that manages the taglets.
1.200 + * @param doc the Doc that we are print tags for.
1.201 + * @param taglets the taglets to print.
1.202 + * @param writer the writer that will generate the output strings.
1.203 + * @param output the output buffer to store the output in.
1.204 + */
1.205 + public static void genTagOuput(TagletManager tagletManager, Doc doc,
1.206 + Taglet[] taglets, TagletWriter writer, Content output) {
1.207 + tagletManager.checkTags(doc, doc.tags(), false);
1.208 + tagletManager.checkTags(doc, doc.inlineTags(), true);
1.209 + Content currentOutput = null;
1.210 + for (int i = 0; i < taglets.length; i++) {
1.211 + currentOutput = null;
1.212 + if (doc instanceof ClassDoc && taglets[i] instanceof ParamTaglet) {
1.213 + //The type parameters are documented in a special section away
1.214 + //from the tag info, so skip here.
1.215 + continue;
1.216 + }
1.217 + if (taglets[i] instanceof DeprecatedTaglet) {
1.218 + //Deprecated information is documented "inline", not in tag info
1.219 + //section.
1.220 + continue;
1.221 + }
1.222 + try {
1.223 + currentOutput = taglets[i].getTagletOutput(doc, writer);
1.224 + } catch (IllegalArgumentException e) {
1.225 + //The taglet does not take a member as an argument. Let's try
1.226 + //a single tag.
1.227 + Tag[] tags = doc.tags(taglets[i].getName());
1.228 + if (tags.length > 0) {
1.229 + currentOutput = taglets[i].getTagletOutput(tags[0], writer);
1.230 + }
1.231 + }
1.232 + if (currentOutput != null) {
1.233 + tagletManager.seenCustomTag(taglets[i].getName());
1.234 + output.addContent(currentOutput);
1.235 + }
1.236 + }
1.237 + }
1.238 +
1.239 + /**
1.240 + * Given an inline tag, return its output.
1.241 + * @param tagletManager The taglet manager for the current doclet.
1.242 + * @param holderTag The tag this holds this inline tag. Null if there
1.243 + * is no tag that holds it.
1.244 + * @param inlineTag The inline tag to be documented.
1.245 + * @param tagletWriter The taglet writer to write the output.
1.246 + * @return The output of the inline tag.
1.247 + */
1.248 + public static Content getInlineTagOuput(TagletManager tagletManager,
1.249 + Tag holderTag, Tag inlineTag, TagletWriter tagletWriter) {
1.250 + Taglet[] definedTags = tagletManager.getInlineCustomTaglets();
1.251 + //This is a custom inline tag.
1.252 + for (int j = 0; j < definedTags.length; j++) {
1.253 + if (("@"+definedTags[j].getName()).equals(inlineTag.name())) {
1.254 + //Given a name of a seen custom tag, remove it from the
1.255 + // set of unseen custom tags.
1.256 + tagletManager.seenCustomTag(definedTags[j].getName());
1.257 + Content output = definedTags[j].getTagletOutput(
1.258 + holderTag != null &&
1.259 + definedTags[j].getName().equals("inheritDoc") ?
1.260 + holderTag : inlineTag, tagletWriter);
1.261 + return output;
1.262 + }
1.263 + }
1.264 + return null;
1.265 + }
1.266 +
1.267 + /**
1.268 + * Converts inline tags and text to TagOutput, expanding the
1.269 + * inline tags along the way. Called wherever text can contain
1.270 + * an inline tag, such as in comments or in free-form text arguments
1.271 + * to non-inline tags.
1.272 + *
1.273 + * @param holderTag the tag that holds the documentation.
1.274 + * @param tags array of text tags and inline tags (often alternating)
1.275 + * present in the text of interest for this doc.
1.276 + * @return the {@link Content} representing the comments.
1.277 + */
1.278 + public abstract Content commentTagsToOutput(Tag holderTag, Tag[] tags);
1.279 +
1.280 + /**
1.281 + * Converts inline tags and text to TagOutput, expanding the
1.282 + * inline tags along the way. Called wherever text can contain
1.283 + * an inline tag, such as in comments or in free-form text arguments
1.284 + * to non-inline tags.
1.285 + *
1.286 + * @param holderDoc specific doc where comment resides.
1.287 + * @param tags array of text tags and inline tags (often alternating)
1.288 + * present in the text of interest for this doc.
1.289 + * @return the {@link Content} representing the comments.
1.290 + */
1.291 + public abstract Content commentTagsToOutput(Doc holderDoc, Tag[] tags);
1.292 +
1.293 + /**
1.294 + * Converts inline tags and text to TagOutput, expanding the
1.295 + * inline tags along the way. Called wherever text can contain
1.296 + * an inline tag, such as in comments or in free-form text arguments
1.297 + * to non-inline tags.
1.298 + *
1.299 + * @param holderTag the tag that holds the documentation.
1.300 + * @param holderDoc specific doc where comment resides.
1.301 + * @param tags array of text tags and inline tags (often alternating)
1.302 + * present in the text of interest for this doc.
1.303 + * @param isFirstSentence true if this is the first sentence.
1.304 + * @return the {@link Content} representing the comments.
1.305 + */
1.306 + public abstract Content commentTagsToOutput(Tag holderTag,
1.307 + Doc holderDoc, Tag[] tags, boolean isFirstSentence);
1.308 +
1.309 + /**
1.310 + * @return an instance of the configuration used for this doclet.
1.311 + */
1.312 + public abstract Configuration configuration();
1.313 +}
