1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/TagletWriterImpl.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,353 @@
1.4 +/*
1.5 + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.formats.html;
1.30 +
1.31 +import com.sun.javadoc.*;
1.32 +import com.sun.tools.doclets.formats.html.markup.ContentBuilder;
1.33 +import com.sun.tools.doclets.formats.html.markup.HtmlStyle;
1.34 +import com.sun.tools.doclets.formats.html.markup.HtmlTree;
1.35 +import com.sun.tools.doclets.formats.html.markup.RawHtml;
1.36 +import com.sun.tools.doclets.formats.html.markup.StringContent;
1.37 +import com.sun.tools.doclets.internal.toolkit.*;
1.38 +import com.sun.tools.doclets.internal.toolkit.builders.SerializedFormBuilder;
1.39 +import com.sun.tools.doclets.internal.toolkit.taglets.*;
1.40 +import com.sun.tools.doclets.internal.toolkit.util.*;
1.41 +
1.42 +/**
1.43 + * The taglet writer that writes HTML.
1.44 + *
1.45 + * <p><b>This is NOT part of any supported API.
1.46 + * If you write code that depends on this, you do so at your own risk.
1.47 + * This code and its internal interfaces are subject to change or
1.48 + * deletion without notice.</b>
1.49 + *
1.50 + * @since 1.5
1.51 + * @author Jamie Ho
1.52 + * @author Bhavesh Patel (Modified)
1.53 + */
1.54 +
1.55 +public class TagletWriterImpl extends TagletWriter {
1.56 +
1.57 + private final HtmlDocletWriter htmlWriter;
1.58 + private final ConfigurationImpl configuration;
1.59 +
1.60 + public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence) {
1.61 + super(isFirstSentence);
1.62 + this.htmlWriter = htmlWriter;
1.63 + configuration = htmlWriter.configuration;
1.64 + }
1.65 +
1.66 + /**
1.67 + * {@inheritDoc}
1.68 + */
1.69 + public Content getOutputInstance() {
1.70 + return new ContentBuilder();
1.71 + }
1.72 +
1.73 + /**
1.74 + * {@inheritDoc}
1.75 + */
1.76 + protected Content codeTagOutput(Tag tag) {
1.77 + Content result = HtmlTree.CODE(new StringContent(Util.normalizeNewlines(tag.text())));
1.78 + return result;
1.79 + }
1.80 +
1.81 + /**
1.82 + * {@inheritDoc}
1.83 + */
1.84 + public Content getDocRootOutput() {
1.85 + String path;
1.86 + if (htmlWriter.pathToRoot.isEmpty())
1.87 + path = ".";
1.88 + else
1.89 + path = htmlWriter.pathToRoot.getPath();
1.90 + return new StringContent(path);
1.91 + }
1.92 +
1.93 + /**
1.94 + * {@inheritDoc}
1.95 + */
1.96 + public Content deprecatedTagOutput(Doc doc) {
1.97 + ContentBuilder result = new ContentBuilder();
1.98 + Tag[] deprs = doc.tags("deprecated");
1.99 + if (doc instanceof ClassDoc) {
1.100 + if (Util.isDeprecated((ProgramElementDoc) doc)) {
1.101 + result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
1.102 + new StringContent(configuration.getText("doclet.Deprecated"))));
1.103 + result.addContent(RawHtml.nbsp);
1.104 + if (deprs.length > 0) {
1.105 + Tag[] commentTags = deprs[0].inlineTags();
1.106 + if (commentTags.length > 0) {
1.107 + result.addContent(commentTagsToOutput(null, doc,
1.108 + deprs[0].inlineTags(), false)
1.109 + );
1.110 + }
1.111 + }
1.112 + }
1.113 + } else {
1.114 + MemberDoc member = (MemberDoc) doc;
1.115 + if (Util.isDeprecated((ProgramElementDoc) doc)) {
1.116 + result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
1.117 + new StringContent(configuration.getText("doclet.Deprecated"))));
1.118 + result.addContent(RawHtml.nbsp);
1.119 + if (deprs.length > 0) {
1.120 + Content body = commentTagsToOutput(null, doc,
1.121 + deprs[0].inlineTags(), false);
1.122 + if (!body.isEmpty())
1.123 + result.addContent(HtmlTree.SPAN(HtmlStyle.deprecationComment, body));
1.124 + }
1.125 + } else {
1.126 + if (Util.isDeprecated(member.containingClass())) {
1.127 + result.addContent(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
1.128 + new StringContent(configuration.getText("doclet.Deprecated"))));
1.129 + result.addContent(RawHtml.nbsp);
1.130 + }
1.131 + }
1.132 + }
1.133 + return result;
1.134 + }
1.135 +
1.136 + /**
1.137 + * {@inheritDoc}
1.138 + */
1.139 + protected Content literalTagOutput(Tag tag) {
1.140 + Content result = new StringContent(Util.normalizeNewlines(tag.text()));
1.141 + return result;
1.142 + }
1.143 +
1.144 + /**
1.145 + * {@inheritDoc}
1.146 + */
1.147 + public MessageRetriever getMsgRetriever() {
1.148 + return configuration.message;
1.149 + }
1.150 +
1.151 + /**
1.152 + * {@inheritDoc}
1.153 + */
1.154 + public Content getParamHeader(String header) {
1.155 + HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.paramLabel,
1.156 + new StringContent(header)));
1.157 + return result;
1.158 + }
1.159 +
1.160 + /**
1.161 + * {@inheritDoc}
1.162 + */
1.163 + public Content paramTagOutput(ParamTag paramTag, String paramName) {
1.164 + ContentBuilder body = new ContentBuilder();
1.165 + body.addContent(HtmlTree.CODE(new RawHtml(paramName)));
1.166 + body.addContent(" - ");
1.167 + body.addContent(htmlWriter.commentTagsToContent(paramTag, null, paramTag.inlineTags(), false));
1.168 + HtmlTree result = HtmlTree.DD(body);
1.169 + return result;
1.170 + }
1.171 +
1.172 + /**
1.173 + * {@inheritDoc}
1.174 + */
1.175 + public Content propertyTagOutput(Tag tag, String prefix) {
1.176 + Content body = new ContentBuilder();
1.177 + body.addContent(new RawHtml(prefix));
1.178 + body.addContent(" ");
1.179 + body.addContent(HtmlTree.CODE(new RawHtml(tag.text())));
1.180 + body.addContent(".");
1.181 + Content result = HtmlTree.P(body);
1.182 + return result;
1.183 + }
1.184 +
1.185 + /**
1.186 + * {@inheritDoc}
1.187 + */
1.188 + public Content returnTagOutput(Tag returnTag) {
1.189 + ContentBuilder result = new ContentBuilder();
1.190 + result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.returnLabel,
1.191 + new StringContent(configuration.getText("doclet.Returns")))));
1.192 + result.addContent(HtmlTree.DD(htmlWriter.commentTagsToContent(
1.193 + returnTag, null, returnTag.inlineTags(), false)));
1.194 + return result;
1.195 + }
1.196 +
1.197 + /**
1.198 + * {@inheritDoc}
1.199 + */
1.200 + public Content seeTagOutput(Doc holder, SeeTag[] seeTags) {
1.201 + ContentBuilder body = new ContentBuilder();
1.202 + if (seeTags.length > 0) {
1.203 + for (int i = 0; i < seeTags.length; ++i) {
1.204 + appendSeparatorIfNotEmpty(body);
1.205 + body.addContent(htmlWriter.seeTagToContent(seeTags[i]));
1.206 + }
1.207 + }
1.208 + if (holder.isField() && ((FieldDoc)holder).constantValue() != null &&
1.209 + htmlWriter instanceof ClassWriterImpl) {
1.210 + //Automatically add link to constant values page for constant fields.
1.211 + appendSeparatorIfNotEmpty(body);
1.212 + DocPath constantsPath =
1.213 + htmlWriter.pathToRoot.resolve(DocPaths.CONSTANT_VALUES);
1.214 + String whichConstant =
1.215 + ((ClassWriterImpl) htmlWriter).getClassDoc().qualifiedName() + "." + ((FieldDoc) holder).name();
1.216 + DocLink link = constantsPath.fragment(whichConstant);
1.217 + body.addContent(htmlWriter.getHyperLink(link,
1.218 + new StringContent(configuration.getText("doclet.Constants_Summary"))));
1.219 + }
1.220 + if (holder.isClass() && ((ClassDoc)holder).isSerializable()) {
1.221 + //Automatically add link to serialized form page for serializable classes.
1.222 + if ((SerializedFormBuilder.serialInclude(holder) &&
1.223 + SerializedFormBuilder.serialInclude(((ClassDoc)holder).containingPackage()))) {
1.224 + appendSeparatorIfNotEmpty(body);
1.225 + DocPath serialPath = htmlWriter.pathToRoot.resolve(DocPaths.SERIALIZED_FORM);
1.226 + DocLink link = serialPath.fragment(((ClassDoc)holder).qualifiedName());
1.227 + body.addContent(htmlWriter.getHyperLink(link,
1.228 + new StringContent(configuration.getText("doclet.Serialized_Form"))));
1.229 + }
1.230 + }
1.231 + if (body.isEmpty())
1.232 + return body;
1.233 +
1.234 + ContentBuilder result = new ContentBuilder();
1.235 + result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.seeLabel,
1.236 + new StringContent(configuration.getText("doclet.See_Also")))));
1.237 + result.addContent(HtmlTree.DD(body));
1.238 + return result;
1.239 +
1.240 + }
1.241 +
1.242 + private void appendSeparatorIfNotEmpty(ContentBuilder body) {
1.243 + if (!body.isEmpty()) {
1.244 + body.addContent(", ");
1.245 + body.addContent(DocletConstants.NL);
1.246 + }
1.247 + }
1.248 +
1.249 + /**
1.250 + * {@inheritDoc}
1.251 + */
1.252 + public Content simpleTagOutput(Tag[] simpleTags, String header) {
1.253 + ContentBuilder result = new ContentBuilder();
1.254 + result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
1.255 + ContentBuilder body = new ContentBuilder();
1.256 + for (int i = 0; i < simpleTags.length; i++) {
1.257 + if (i > 0) {
1.258 + body.addContent(", ");
1.259 + }
1.260 + body.addContent(htmlWriter.commentTagsToContent(
1.261 + simpleTags[i], null, simpleTags[i].inlineTags(), false));
1.262 + }
1.263 + result.addContent(HtmlTree.DD(body));
1.264 + return result;
1.265 + }
1.266 +
1.267 + /**
1.268 + * {@inheritDoc}
1.269 + */
1.270 + public Content simpleTagOutput(Tag simpleTag, String header) {
1.271 + ContentBuilder result = new ContentBuilder();
1.272 + result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
1.273 + Content body = htmlWriter.commentTagsToContent(
1.274 + simpleTag, null, simpleTag.inlineTags(), false);
1.275 + result.addContent(HtmlTree.DD(body));
1.276 + return result;
1.277 + }
1.278 +
1.279 + /**
1.280 + * {@inheritDoc}
1.281 + */
1.282 + public Content getThrowsHeader() {
1.283 + HtmlTree result = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.throwsLabel,
1.284 + new StringContent(configuration.getText("doclet.Throws"))));
1.285 + return result;
1.286 + }
1.287 +
1.288 + /**
1.289 + * {@inheritDoc}
1.290 + */
1.291 + public Content throwsTagOutput(ThrowsTag throwsTag) {
1.292 + ContentBuilder body = new ContentBuilder();
1.293 + Content excName = (throwsTag.exceptionType() == null) ?
1.294 + new RawHtml(throwsTag.exceptionName()) :
1.295 + htmlWriter.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER,
1.296 + throwsTag.exceptionType()));
1.297 + body.addContent(HtmlTree.CODE(excName));
1.298 + Content desc = htmlWriter.commentTagsToContent(throwsTag, null,
1.299 + throwsTag.inlineTags(), false);
1.300 + if (desc != null && !desc.isEmpty()) {
1.301 + body.addContent(" - ");
1.302 + body.addContent(desc);
1.303 + }
1.304 + HtmlTree result = HtmlTree.DD(body);
1.305 + return result;
1.306 + }
1.307 +
1.308 + /**
1.309 + * {@inheritDoc}
1.310 + */
1.311 + public Content throwsTagOutput(Type throwsType) {
1.312 + HtmlTree result = HtmlTree.DD(HtmlTree.CODE(htmlWriter.getLink(
1.313 + new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER, throwsType))));
1.314 + return result;
1.315 + }
1.316 +
1.317 + /**
1.318 + * {@inheritDoc}
1.319 + */
1.320 + public Content valueTagOutput(FieldDoc field, String constantVal,
1.321 + boolean includeLink) {
1.322 + return includeLink ?
1.323 + htmlWriter.getDocLink(LinkInfoImpl.Kind.VALUE_TAG, field,
1.324 + constantVal, false) : new RawHtml(constantVal);
1.325 + }
1.326 +
1.327 + /**
1.328 + * {@inheritDoc}
1.329 + */
1.330 + public Content commentTagsToOutput(Tag holderTag, Tag[] tags) {
1.331 + return commentTagsToOutput(holderTag, null, tags, false);
1.332 + }
1.333 +
1.334 + /**
1.335 + * {@inheritDoc}
1.336 + */
1.337 + public Content commentTagsToOutput(Doc holderDoc, Tag[] tags) {
1.338 + return commentTagsToOutput(null, holderDoc, tags, false);
1.339 + }
1.340 +
1.341 + /**
1.342 + * {@inheritDoc}
1.343 + */
1.344 + public Content commentTagsToOutput(Tag holderTag,
1.345 + Doc holderDoc, Tag[] tags, boolean isFirstSentence) {
1.346 + return htmlWriter.commentTagsToContent(
1.347 + holderTag, holderDoc, tags, isFirstSentence);
1.348 + }
1.349 +
1.350 + /**
1.351 + * {@inheritDoc}
1.352 + */
1.353 + public Configuration configuration() {
1.354 + return configuration;
1.355 + }
1.356 +}
