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