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