Tue, 14 May 2013 10:14:54 -0700
8012175: Convert TagletOutputImpl to use ContentBuilder instead of StringBuilder
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2001, 2013, 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 */
26 package com.sun.tools.doclets.internal.toolkit.taglets;
28 import com.sun.javadoc.*;
29 import com.sun.tools.doclets.internal.toolkit.Configuration;
30 import com.sun.tools.doclets.internal.toolkit.util.*;
32 /**
33 * An inline Taglet representing the <b>inheritDoc</b> tag. This tag should only
34 * be used with a method. It is used to inherit documentation from overriden
35 * and implemented methods.
36 *
37 * <p><b>This is NOT part of any supported API.
38 * If you write code that depends on this, you do so at your own risk.
39 * This code and its internal interfaces are subject to change or
40 * deletion without notice.</b>
41 *
42 * @author Jamie Ho
43 * @since 1.4
44 */
46 public class InheritDocTaglet extends BaseInlineTaglet {
48 /**
49 * The inline tag that would appear in the documentation if
50 * the writer wanted documentation to be inherited.
51 */
52 public static final String INHERIT_DOC_INLINE_TAG = "{@inheritDoc}";
54 /**
55 * Construct a new InheritDocTaglet.
56 */
57 public InheritDocTaglet () {
58 name = "inheritDoc";
59 }
61 /**
62 * Will return false because this inline tag may
63 * not appear in Fields.
64 * @return false
65 */
66 public boolean inField() {
67 return false;
68 }
70 /**
71 * Will return false because this inline tag may
72 * not appear in Constructors.
73 * @return false
74 */
75 public boolean inConstructor() {
76 return false;
77 }
79 /**
80 * Will return false because this inline tag may
81 * not appear in Overview.
82 * @return false
83 */
84 public boolean inOverview() {
85 return false;
86 }
88 /**
89 * Will return false because this inline tag may
90 * not appear in Packages.
91 * @return false
92 */
93 public boolean inPackage() {
94 return false;
95 }
97 /**
98 * Will return true because this inline tag may
99 * appear in Type (Class).
100 * @return true
101 */
102 public boolean inType() {
103 return true;
104 }
106 /**
107 * Given a <code>MethodDoc</code> item, a <code>Tag</code> in the
108 * <code>MethodDoc</code> item and a String, replace all occurrences
109 * of @inheritDoc with documentation from it's superclass or superinterface.
110 *
111 * @param writer the writer that is writing the output.
112 * @param ped the {@link ProgramElementDoc} that we are documenting.
113 * @param holderTag the tag that holds the inheritDoc tag or null for type
114 * (class) docs.
115 * @param isFirstSentence true if we only want to inherit the first sentence.
116 */
117 private TagletOutput retrieveInheritedDocumentation(TagletWriter writer,
118 ProgramElementDoc ped, Tag holderTag, boolean isFirstSentence) {
119 TagletOutput replacement = writer.getOutputInstance();
121 Configuration configuration = writer.configuration();
122 Taglet inheritableTaglet = holderTag == null ?
123 null : configuration.tagletManager.getTaglet(holderTag.name());
124 if (inheritableTaglet != null &&
125 !(inheritableTaglet instanceof InheritableTaglet)) {
126 String message = ped.name() +
127 ((ped instanceof ExecutableMemberDoc)
128 ? ((ExecutableMemberDoc)ped).flatSignature()
129 : "");
130 //This tag does not support inheritence.
131 configuration.message.warning(ped.position(),
132 "doclet.noInheritedDoc", message);
133 }
134 DocFinder.Output inheritedDoc =
135 DocFinder.search(new DocFinder.Input(ped,
136 (InheritableTaglet) inheritableTaglet, holderTag,
137 isFirstSentence, true));
138 if (inheritedDoc.isValidInheritDocTag) {
139 if (inheritedDoc.inlineTags.length > 0) {
140 replacement = writer.commentTagsToOutput(inheritedDoc.holderTag,
141 inheritedDoc.holder, inheritedDoc.inlineTags, isFirstSentence);
142 }
143 } else {
144 String message = ped.name() +
145 ((ped instanceof ExecutableMemberDoc)
146 ? ((ExecutableMemberDoc)ped).flatSignature()
147 : "");
148 configuration.message.warning(ped.position(),
149 "doclet.noInheritedDoc", message);
150 }
151 return replacement;
152 }
154 /**
155 * Given the <code>Tag</code> representation of this custom
156 * tag, return its string representation, which is output
157 * to the generated page.
158 * @param tag the <code>Tag</code> representation of this custom tag.
159 * @param tagletWriter the taglet writer for output.
160 * @return the TagletOutput representation of this <code>Tag</code>.
161 */
162 public TagletOutput getTagletOutput(Tag tag, TagletWriter tagletWriter) {
163 if (! (tag.holder() instanceof ProgramElementDoc)) {
164 return tagletWriter.getOutputInstance();
165 }
166 return tag.name().equals("@inheritDoc") ?
167 retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
168 retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
169 }
170 }