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