Sat, 08 Sep 2012 22:43:38 -0700
7180906: Javadoc tool does not apply parameter -nosince
Reviewed-by: jjg
1 /*
2 * Copyright (c) 2003, 2005, 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 */
26 package com.sun.tools.doclets.internal.toolkit.taglets;
28 import com.sun.tools.doclets.internal.toolkit.*;
29 import com.sun.tools.doclets.internal.toolkit.util.*;
30 import com.sun.javadoc.*;
32 /**
33 * The interface for the taglet writer.
34 *
35 * @since 1.5
36 * @author Jamie Ho
37 */
39 public abstract class TagletWriter {
41 /**
42 * True if we only want to write the first sentence.
43 */
44 protected boolean isFirstSentence = false;
46 /**
47 * @return an instance of the output object.
48 */
49 public abstract TagletOutput getOutputInstance();
51 /**
52 * Returns the output for the DocRoot inline tag.
53 * @return the output for the DocRoot inline tag.
54 */
55 protected abstract TagletOutput getDocRootOutput();
57 /**
58 * Return the deprecated tag output.
59 *
60 * @param doc the doc to write deprecated documentation for.
61 * @return the output of the deprecated tag.
62 */
63 protected abstract TagletOutput deprecatedTagOutput(Doc doc);
65 /**
66 * Returns {@link MessageRetriever} for output purposes.
67 *
68 * @return {@link MessageRetriever} for output purposes.
69 */
70 protected abstract MessageRetriever getMsgRetriever();
72 /**
73 * Return the header for the param tags.
74 *
75 * @param header the header to display.
76 * @return the header for the param tags.
77 */
78 protected abstract TagletOutput getParamHeader(String header);
80 /**
81 * Return the output for param tags.
82 *
83 * @param paramTag the parameter to document.
84 * @param paramName the name of the parameter.
85 * @return the output of the param tag.
86 */
87 protected abstract TagletOutput paramTagOutput(ParamTag paramTag,
88 String paramName);
90 /**
91 * Return the return tag output.
92 *
93 * @param returnTag the return tag to output.
94 * @return the output of the return tag.
95 */
96 protected abstract TagletOutput returnTagOutput(Tag returnTag);
98 /**
99 * Return the see tag output.
100 *
101 * @param seeTags the array of See tags.
102 * @return the output of the see tags.
103 */
104 protected abstract TagletOutput seeTagOutput(Doc holder, SeeTag[] seeTags);
106 /**
107 * Return the output for a simple tag.
108 *
109 * @param simpleTags the array of simple tags.
110 * @return the output of the simple tags.
111 */
112 protected abstract TagletOutput simpleTagOutput(Tag[] simpleTags,
113 String header);
115 /**
116 * Return the output for a simple tag.
117 *
118 * @param simpleTag the simple tag.
119 * @return the output of the simple tag.
120 */
121 protected abstract TagletOutput simpleTagOutput(Tag simpleTag, String header);
123 /**
124 * Return the header for the throws tag.
125 *
126 * @return the header for the throws tag.
127 */
128 protected abstract TagletOutput getThrowsHeader();
130 /**
131 * Return the header for the throws tag.
132 *
133 * @param throwsTag the throws tag.
134 * @return the output of the throws tag.
135 */
136 protected abstract TagletOutput throwsTagOutput(ThrowsTag throwsTag);
138 /**
139 * Return the output for the throws tag.
140 *
141 * @param throwsType the throws type.
142 * @return the output of the throws type.
143 */
144 protected abstract TagletOutput throwsTagOutput(Type throwsType);
146 /**
147 * Return the output for the value tag.
148 *
149 * @param field the constant field that holds the value tag.
150 * @param constantVal the constant value to document.
151 * @param includeLink true if we should link the constant text to the
152 * constant field itself.
153 * @return the output of the value tag.
154 */
155 protected abstract TagletOutput valueTagOutput(FieldDoc field,
156 String constantVal, boolean includeLink);
158 /**
159 * Given an output object, append to it the tag documentation for
160 * the given member.
161 *
162 * @param tagletManager the manager that manages the taglets.
163 * @param doc the Doc that we are print tags for.
164 * @param taglets the taglets to print.
165 * @param writer the writer that will generate the output strings.
166 * @param output the output buffer to store the output in.
167 */
168 public static void genTagOuput(TagletManager tagletManager, Doc doc,
169 Taglet[] taglets, TagletWriter writer, TagletOutput output) {
170 tagletManager.checkTags(doc, doc.tags(), false);
171 tagletManager.checkTags(doc, doc.inlineTags(), true);
172 TagletOutput currentOutput = null;
173 for (int i = 0; i < taglets.length; i++) {
174 if (doc instanceof ClassDoc && taglets[i] instanceof ParamTaglet) {
175 //The type parameters are documented in a special section away
176 //from the tag info, so skip here.
177 continue;
178 }
179 if (taglets[i] instanceof DeprecatedTaglet) {
180 //Deprecated information is documented "inline", not in tag info
181 //section.
182 continue;
183 }
184 try {
185 currentOutput = taglets[i].getTagletOutput(doc, writer);
186 } catch (IllegalArgumentException e) {
187 //The taglet does not take a member as an argument. Let's try
188 //a single tag.
189 Tag[] tags = doc.tags(taglets[i].getName());
190 if (tags.length > 0) {
191 currentOutput = taglets[i].getTagletOutput(tags[0], writer);
192 }
193 }
194 if (currentOutput != null) {
195 tagletManager.seenCustomTag(taglets[i].getName());
196 output.appendOutput(currentOutput);
197 }
198 }
199 }
201 /**
202 * Given an inline tag, return its output.
203 * @param tagletManager The taglet manager for the current doclet.
204 * @param holderTag The tag this holds this inline tag. Null if there
205 * is no tag that holds it.
206 * @param inlineTag The inline tag to be documented.
207 * @param tagletWriter The taglet writer to write the output.
208 * @return The output of the inline tag.
209 */
210 public static TagletOutput getInlineTagOuput(TagletManager tagletManager,
211 Tag holderTag, Tag inlineTag, TagletWriter tagletWriter) {
212 Taglet[] definedTags = tagletManager.getInlineCustomTags();
213 //This is a custom inline tag.
214 for (int j = 0; j < definedTags.length; j++) {
215 if (("@"+definedTags[j].getName()).equals(inlineTag.name())) {
216 //Given a name of a seen custom tag, remove it from the
217 // set of unseen custom tags.
218 tagletManager.seenCustomTag(definedTags[j].getName());
219 TagletOutput output = definedTags[j].getTagletOutput(
220 holderTag != null &&
221 definedTags[j].getName().equals("inheritDoc") ?
222 holderTag : inlineTag, tagletWriter);
223 return output;
224 }
225 }
226 return null;
227 }
229 /**
230 * Converts inline tags and text to TagOutput, expanding the
231 * inline tags along the way. Called wherever text can contain
232 * an inline tag, such as in comments or in free-form text arguments
233 * to non-inline tags.
234 *
235 * @param holderTag the tag that holds the documentation.
236 * @param tags array of text tags and inline tags (often alternating)
237 * present in the text of interest for this doc.
238 * @return the {@link TagletOutput} representing the comments.
239 */
240 public abstract TagletOutput commentTagsToOutput(Tag holderTag, Tag[] tags);
242 /**
243 * Converts inline tags and text to TagOutput, expanding the
244 * inline tags along the way. Called wherever text can contain
245 * an inline tag, such as in comments or in free-form text arguments
246 * to non-inline tags.
247 *
248 * @param holderDoc specific doc where comment resides.
249 * @param tags array of text tags and inline tags (often alternating)
250 * present in the text of interest for this doc.
251 * @return the {@link TagletOutput} representing the comments.
252 */
253 public abstract TagletOutput commentTagsToOutput(Doc holderDoc, Tag[] tags);
255 /**
256 * Converts inline tags and text to TagOutput, expanding the
257 * inline tags along the way. Called wherever text can contain
258 * an inline tag, such as in comments or in free-form text arguments
259 * to non-inline tags.
260 *
261 * @param holderTag the tag that holds the documentation.
262 * @param holderDoc specific doc where comment resides.
263 * @param tags array of text tags and inline tags (often alternating)
264 * present in the text of interest for this doc.
265 * @param isFirstSentence true if this is the first sentence.
266 * @return the {@link TagletOutput} representing the comments.
267 */
268 public abstract TagletOutput commentTagsToOutput(Tag holderTag,
269 Doc holderDoc, Tag[] tags, boolean isFirstSentence);
271 /**
272 * @return an instance of the configuration used for this doclet.
273 */
274 public abstract Configuration configuration();
276 /**
277 * @return an instance of the taglet output object.
278 */
279 public abstract TagletOutput getTagletOutputInstance();
280 }