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