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