Mercurial > jdk8-mips64-public > langtools / file comparison

comparison: src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletWriter.java

src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/TagletWriter.java

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

Mercurial Repository: jdk8-mips64-public/langtools

mercurial