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