1 /*
2 * Copyright (c) 2003, 2018, 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 jdk.javadoc.internal.doclets.formats.html;
27
28 import java.util.List;
29
30 import javax.lang.model.element.Element;
31 import javax.lang.model.element.ModuleElement;
32 import javax.lang.model.element.PackageElement;
33 import javax.lang.model.element.TypeElement;
34 import javax.lang.model.element.VariableElement;
35 import javax.lang.model.type.TypeMirror;
36 import javax.lang.model.util.SimpleElementVisitor9;
37
38 import com.sun.source.doctree.DocTree;
39 import com.sun.source.doctree.IndexTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
41 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
42 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
43 import jdk.javadoc.internal.doclets.formats.html.markup.Links;
44 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
45 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
46 import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
47 import jdk.javadoc.internal.doclets.toolkit.Content;
48 import jdk.javadoc.internal.doclets.toolkit.builders.SerializedFormBuilder;
49 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
50 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
51 import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
52 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
53 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
54 import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
55 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
56
57 /**
58 * The taglet writer that writes HTML.
59 *
60 * <p><b>This is NOT part of any supported API.
61 * If you write code that depends on this, you do so at your own risk.
62 * This code and its internal interfaces are subject to change or
63 * deletion without notice.</b>
64 *
65 * @author Jamie Ho
66 * @author Bhavesh Patel (Modified)
67 */
68
69 public class TagletWriterImpl extends TagletWriter {
70
71 private final HtmlDocletWriter htmlWriter;
72 private final HtmlConfiguration configuration;
73 private final Utils utils;
74
75 public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence) {
76 super(isFirstSentence);
77 this.htmlWriter = htmlWriter;
78 configuration = htmlWriter.configuration;
79 this.utils = configuration.utils;
80 }
81
82 /**
83 * {@inheritDoc}
84 */
85 public Content getOutputInstance() {
86 return new ContentBuilder();
87 }
88
89 /**
90 * {@inheritDoc}
91 */
92 protected Content codeTagOutput(Element element, DocTree tag) {
93 CommentHelper ch = utils.getCommentHelper(element);
94 StringContent content = new StringContent(utils.normalizeNewlines(ch.getText(tag)));
95 Content result = HtmlTree.CODE(content);
96 return result;
97 }
98
99 protected Content indexTagOutput(Element element, DocTree tag) {
100 CommentHelper ch = utils.getCommentHelper(element);
101 IndexTree itt = (IndexTree)tag;
102
103 String tagText = ch.getText(itt.getSearchTerm());
104 if (tagText.charAt(0) == '"' && tagText.charAt(tagText.length() - 1) == '"') {
105 tagText = tagText.substring(1, tagText.length() - 1);
106 }
107 String desc = ch.getText(itt.getDescription());
108
109 String anchorName = htmlWriter.links.getName(tagText);
110 Content result = HtmlTree.A_ID(HtmlStyle.searchTagResult, anchorName, new StringContent(tagText));
111 if (configuration.createindex && !tagText.isEmpty()) {
112 SearchIndexItem si = new SearchIndexItem();
113 si.setLabel(tagText);
114 si.setDescription(desc);
115 DocPaths docPaths = configuration.docPaths;
116 new SimpleElementVisitor9<Void, Void>() {
117 @Override
118 public Void visitModule(ModuleElement e, Void p) {
119 si.setUrl(docPaths.moduleSummary(e).getPath() + "#" + anchorName);
120 si.setHolder(utils.getFullyQualifiedName(element));
121 return null;
122 }
123
124 @Override
125 public Void visitPackage(PackageElement e, Void p) {
126 si.setUrl(docPaths.forPackage(e).getPath()
127 + "/" + DocPaths.PACKAGE_SUMMARY.getPath() + "#" + anchorName);
128 si.setHolder(utils.getSimpleName(element));
129 return null;
130 }
131
132 @Override
133 public Void visitType(TypeElement e, Void p) {
134 si.setUrl(docPaths.forClass(e).getPath() + "#" + anchorName);
135 si.setHolder(utils.getFullyQualifiedName(e));
136 return null;
137 }
138
139 @Override
140 public Void visitVariable(VariableElement e, Void p) {
141 TypeElement te = utils.getEnclosingTypeElement(e);
142 si.setUrl(docPaths.forClass(te).getPath() + "#" + anchorName);
143 si.setHolder(utils.getFullyQualifiedName(e) + "." + utils.getSimpleName(e));
144 return null;
145 }
146
147 @Override
148 protected Void defaultAction(Element e, Void p) {
149 TypeElement te = utils.getEnclosingTypeElement(e);
150 si.setUrl(docPaths.forClass(te).getPath() + "#" + anchorName);
151 si.setHolder(utils.getFullyQualifiedName(e));
152 return null;
153 }
154 }.visit(element);
155 si.setCategory(configuration.getContent("doclet.SearchTags").toString());
156 configuration.tagSearchIndex.add(si);
157 }
158 return result;
159 }
160
161 /**
162 * {@inheritDoc}
163 */
164 public Content getDocRootOutput() {
165 String path;
166 if (htmlWriter.pathToRoot.isEmpty())
167 path = ".";
168 else
169 path = htmlWriter.pathToRoot.getPath();
170 return new StringContent(path);
171 }
172
173 /**
174 * {@inheritDoc}
175 */
176 public Content deprecatedTagOutput(Element element) {
177 ContentBuilder result = new ContentBuilder();
178 CommentHelper ch = utils.getCommentHelper(element);
179 List<? extends DocTree> deprs = utils.getBlockTags(element, DocTree.Kind.DEPRECATED);
180 if (utils.isTypeElement(element)) {
181 if (utils.isDeprecated(element)) {
182 result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
183 htmlWriter.getDeprecatedPhrase(element)));
184 if (!deprs.isEmpty()) {
185 List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0));
186 if (!commentTags.isEmpty()) {
187 result.addContent(commentTagsToOutput(null, element, commentTags, false));
188 }
189 }
190 }
191 } else {
192 if (utils.isDeprecated(element)) {
193 result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
194 htmlWriter.getDeprecatedPhrase(element)));
195 if (!deprs.isEmpty()) {
196 List<? extends DocTree> bodyTags = ch.getBody(configuration, deprs.get(0));
197 Content body = commentTagsToOutput(null, element, bodyTags, false);
198 if (!body.isEmpty())
199 result.addContent(HtmlTree.DIV(HtmlStyle.deprecationComment, body));
200 }
201 } else {
202 Element ee = utils.getEnclosingTypeElement(element);
203 if (utils.isDeprecated(ee)) {
204 result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
205 htmlWriter.getDeprecatedPhrase(ee)));
206 }
207 }
208 }
209 return result;
210 }
211
212 /**
213 * {@inheritDoc}
214 */
215 protected Content literalTagOutput(Element element, DocTree tag) {
216 CommentHelper ch = utils.getCommentHelper(element);
217 Content result = new StringContent(utils.normalizeNewlines(ch.getText(tag)));
218 return result;
219 }
220
221 /**
222 * {@inheritDoc}
223 */
224 public Content getParamHeader(String header) {
225 HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.paramLabel,
226 new StringContent(header)));
227 return result;
228 }
229
230 /**
231 * {@inheritDoc}
232 */
233 public Content paramTagOutput(Element element, DocTree paramTag, String paramName) {
234 ContentBuilder body = new ContentBuilder();
235 CommentHelper ch = utils.getCommentHelper(element);
236 body.addContent(HtmlTree.CODE(new RawHtml(paramName)));
237 body.addContent(" - ");
238 List<? extends DocTree> description = ch.getDescription(configuration, paramTag);
239 body.addContent(htmlWriter.commentTagsToContent(paramTag, element, description, false));
240 HtmlTree result = HtmlTree.DD(body);
241 return result;
242 }
243
244 /**
245 * {@inheritDoc}
246 */
247 public Content propertyTagOutput(Element element, DocTree tag, String prefix) {
248 Content body = new ContentBuilder();
249 CommentHelper ch = utils.getCommentHelper(element);
250 body.addContent(new RawHtml(prefix));
251 body.addContent(" ");
252 body.addContent(HtmlTree.CODE(new RawHtml(ch.getText(tag))));
253 body.addContent(".");
254 Content result = HtmlTree.P(body);
255 return result;
256 }
257
258 /**
259 * {@inheritDoc}
260 */
261 public Content returnTagOutput(Element element, DocTree returnTag) {
262 ContentBuilder result = new ContentBuilder();
263 CommentHelper ch = utils.getCommentHelper(element);
264 result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.returnLabel,
265 new StringContent(configuration.getText("doclet.Returns")))));
266 result.addContent(HtmlTree.DD(htmlWriter.commentTagsToContent(
267 returnTag, element, ch.getDescription(configuration, returnTag), false)));
268 return result;
269 }
270
271 /**
272 * {@inheritDoc}
273 */
274 public Content seeTagOutput(Element holder, List<? extends DocTree> seeTags) {
275 ContentBuilder body = new ContentBuilder();
276 if (!seeTags.isEmpty()) {
277 for (DocTree dt : seeTags) {
278 appendSeparatorIfNotEmpty(body);
279 body.addContent(htmlWriter.seeTagToContent(holder, dt));
280 }
281 }
282 if (utils.isVariableElement(holder) && ((VariableElement)holder).getConstantValue() != null &&
283 htmlWriter instanceof ClassWriterImpl) {
284 //Automatically add link to constant values page for constant fields.
285 appendSeparatorIfNotEmpty(body);
286 DocPath constantsPath =
287 htmlWriter.pathToRoot.resolve(DocPaths.CONSTANT_VALUES);
288 String whichConstant =
289 ((ClassWriterImpl) htmlWriter).getTypeElement().getQualifiedName() + "." +
290 utils.getSimpleName(holder);
291 DocLink link = constantsPath.fragment(whichConstant);
292 body.addContent(htmlWriter.links.createLink(link,
293 new StringContent(configuration.getText("doclet.Constants_Summary"))));
294 }
295 if (utils.isClass(holder) && utils.isSerializable((TypeElement)holder)) {
296 //Automatically add link to serialized form page for serializable classes.
297 if (SerializedFormBuilder.serialInclude(utils, holder) &&
298 SerializedFormBuilder.serialInclude(utils, utils.containingPackage(holder))) {
299 appendSeparatorIfNotEmpty(body);
300 DocPath serialPath = htmlWriter.pathToRoot.resolve(DocPaths.SERIALIZED_FORM);
301 DocLink link = serialPath.fragment(utils.getFullyQualifiedName(holder));
302 body.addContent(htmlWriter.links.createLink(link,
303 new StringContent(configuration.getText("doclet.Serialized_Form"))));
304 }
305 }
306 if (body.isEmpty())
307 return body;
308
309 ContentBuilder result = new ContentBuilder();
310 result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.seeLabel,
311 new StringContent(configuration.getText("doclet.See_Also")))));
312 result.addContent(HtmlTree.DD(body));
313 return result;
314
315 }
316
317 private void appendSeparatorIfNotEmpty(ContentBuilder body) {
318 if (!body.isEmpty()) {
319 body.addContent(", ");
320 body.addContent(DocletConstants.NL);
321 }
322 }
323
324 /**
325 * {@inheritDoc}
326 */
327 public Content simpleTagOutput(Element element, List<? extends DocTree> simpleTags, String header) {
328 CommentHelper ch = utils.getCommentHelper(element);
329 ContentBuilder result = new ContentBuilder();
330 result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
331 ContentBuilder body = new ContentBuilder();
332 boolean many = false;
333 for (DocTree simpleTag : simpleTags) {
334 if (many) {
335 body.addContent(", ");
336 }
337 List<? extends DocTree> bodyTags = ch.getBody(configuration, simpleTag);
338 body.addContent(htmlWriter.commentTagsToContent(simpleTag, element, bodyTags, false));
339 many = true;
340 }
341 result.addContent(HtmlTree.DD(body));
342 return result;
343 }
344
345 /**
346 * {@inheritDoc}
347 */
348 public Content simpleTagOutput(Element element, DocTree simpleTag, String header) {
349 ContentBuilder result = new ContentBuilder();
350 result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
351 CommentHelper ch = utils.getCommentHelper(element);
352 List<? extends DocTree> description = ch.getDescription(configuration, simpleTag);
353 Content body = htmlWriter.commentTagsToContent(simpleTag, element, description, false);
354 result.addContent(HtmlTree.DD(body));
355 return result;
356 }
357
358 /**
359 * {@inheritDoc}
360 */
361 public Content getThrowsHeader() {
362 HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.throwsLabel,
363 new StringContent(configuration.getText("doclet.Throws"))));
364 return result;
365 }
366
367 /**
368 * {@inheritDoc}
369 */
370 public Content throwsTagOutput(Element element, DocTree throwsTag) {
371 ContentBuilder body = new ContentBuilder();
372 CommentHelper ch = utils.getCommentHelper(element);
373 Element exception = ch.getException(configuration, throwsTag);
374 Content excName;
375 if (exception == null) {
376 excName = new RawHtml(ch.getExceptionName(throwsTag).toString());
377 } else if (exception.asType() == null) {
378 excName = new RawHtml(utils.getFullyQualifiedName(exception));
379 } else {
380 LinkInfoImpl link = new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER,
381 exception.asType());
382 link.excludeTypeBounds = true;
383 excName = htmlWriter.getLink(link);
384 }
385 body.addContent(HtmlTree.CODE(excName));
386 List<? extends DocTree> description = ch.getDescription(configuration, throwsTag);
387 Content desc = htmlWriter.commentTagsToContent(throwsTag, element, description, false);
388 if (desc != null && !desc.isEmpty()) {
389 body.addContent(" - ");
390 body.addContent(desc);
391 }
392 HtmlTree result = HtmlTree.DD(body);
393 return result;
394 }
395
396 /**
397 * {@inheritDoc}
398 */
399 public Content throwsTagOutput(TypeMirror throwsType) {
400 HtmlTree result = HtmlTree.DD(HtmlTree.CODE(htmlWriter.getLink(
401 new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER, throwsType))));
402 return result;
403 }
404
405 /**
406 * {@inheritDoc}
407 */
408 public Content valueTagOutput(VariableElement field, String constantVal, boolean includeLink) {
409 return includeLink ?
410 htmlWriter.getDocLink(LinkInfoImpl.Kind.VALUE_TAG, field,
411 constantVal, false) : new RawHtml(constantVal);
412 }
413
414 /**
415 * {@inheritDoc}
416 */
417 public Content commentTagsToOutput(DocTree holderTag, List<? extends DocTree> tags) {
418 return commentTagsToOutput(holderTag, null, tags, false);
419 }
420
421 /**
422 * {@inheritDoc}
423 */
424 public Content commentTagsToOutput(Element holder, List<? extends DocTree> tags) {
425 return commentTagsToOutput(null, holder, tags, false);
426 }
427
428 /**
429 * {@inheritDoc}
430 */
431 public Content commentTagsToOutput(DocTree holderTag,
432 Element holder, List<? extends DocTree> tags, boolean isFirstSentence) {
433 return htmlWriter.commentTagsToContent(holderTag, holder,
434 tags, isFirstSentence);
435 }
436
437 /**
438 * {@inheritDoc}
439 */
440 public BaseConfiguration configuration() {
441 return configuration;
442 }
443 }