Tue, 03 Dec 2013 14:21:45 -0800
8025416: doclet not substituting {@docRoot} in some cases
Reviewed-by: jjg
1 /*
2 * Copyright (c) 1997, 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.formats.html;
28 import java.io.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.formats.html.markup.*;
32 import com.sun.tools.doclets.internal.toolkit.*;
33 import com.sun.tools.doclets.internal.toolkit.util.*;
35 /**
36 * Writes method documentation in HTML format.
37 *
38 * <p><b>This is NOT part of any supported API.
39 * If you write code that depends on this, you do so at your own risk.
40 * This code and its internal interfaces are subject to change or
41 * deletion without notice.</b>
42 *
43 * @author Robert Field
44 * @author Atul M Dambalkar
45 * @author Jamie Ho (rewrite)
46 * @author Bhavesh Patel (Modified)
47 */
48 public class MethodWriterImpl extends AbstractExecutableMemberWriter
49 implements MethodWriter, MemberSummaryWriter {
51 /**
52 * Construct a new MethodWriterImpl.
53 *
54 * @param writer the writer for the class that the methods belong to.
55 * @param classDoc the class being documented.
56 */
57 public MethodWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
58 super(writer, classDoc);
59 }
61 /**
62 * Construct a new MethodWriterImpl.
63 *
64 * @param writer The writer for the class that the methods belong to.
65 */
66 public MethodWriterImpl(SubWriterHolderWriter writer) {
67 super(writer);
68 }
70 /**
71 * {@inheritDoc}
72 */
73 public Content getMemberSummaryHeader(ClassDoc classDoc,
74 Content memberSummaryTree) {
75 memberSummaryTree.addContent(HtmlConstants.START_OF_METHOD_SUMMARY);
76 Content memberTree = writer.getMemberTreeHeader();
77 writer.addSummaryHeader(this, classDoc, memberTree);
78 return memberTree;
79 }
81 /**
82 * {@inheritDoc}
83 */
84 public Content getMethodDetailsTreeHeader(ClassDoc classDoc,
85 Content memberDetailsTree) {
86 memberDetailsTree.addContent(HtmlConstants.START_OF_METHOD_DETAILS);
87 Content methodDetailsTree = writer.getMemberTreeHeader();
88 methodDetailsTree.addContent(writer.getMarkerAnchor(
89 SectionName.METHOD_DETAIL));
90 Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
91 writer.methodDetailsLabel);
92 methodDetailsTree.addContent(heading);
93 return methodDetailsTree;
94 }
96 /**
97 * {@inheritDoc}
98 */
99 public Content getMethodDocTreeHeader(MethodDoc method,
100 Content methodDetailsTree) {
101 String erasureAnchor;
102 if ((erasureAnchor = getErasureAnchor(method)) != null) {
103 methodDetailsTree.addContent(writer.getMarkerAnchor((erasureAnchor)));
104 }
105 methodDetailsTree.addContent(
106 writer.getMarkerAnchor(writer.getAnchor(method)));
107 Content methodDocTree = writer.getMemberTreeHeader();
108 Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
109 heading.addContent(method.name());
110 methodDocTree.addContent(heading);
111 return methodDocTree;
112 }
114 /**
115 * Get the signature for the given method.
116 *
117 * @param method the method being documented.
118 * @return a content object for the signature
119 */
120 public Content getSignature(MethodDoc method) {
121 Content pre = new HtmlTree(HtmlTag.PRE);
122 writer.addAnnotationInfo(method, pre);
123 addModifiers(method, pre);
124 addTypeParameters(method, pre);
125 addReturnType(method, pre);
126 if (configuration.linksource) {
127 Content methodName = new StringContent(method.name());
128 writer.addSrcLink(method, methodName, pre);
129 } else {
130 addName(method.name(), pre);
131 }
132 int indent = pre.charCount();
133 addParameters(method, pre, indent);
134 addExceptions(method, pre, indent);
135 return pre;
136 }
138 /**
139 * {@inheritDoc}
140 */
141 public void addDeprecated(MethodDoc method, Content methodDocTree) {
142 addDeprecatedInfo(method, methodDocTree);
143 }
145 /**
146 * {@inheritDoc}
147 */
148 public void addComments(Type holder, MethodDoc method, Content methodDocTree) {
149 ClassDoc holderClassDoc = holder.asClassDoc();
150 if (method.inlineTags().length > 0) {
151 if (holder.asClassDoc().equals(classdoc) ||
152 (! (holderClassDoc.isPublic() ||
153 Util.isLinkable(holderClassDoc, configuration)))) {
154 writer.addInlineComment(method, methodDocTree);
155 } else {
156 Content link =
157 writer.getDocLink(LinkInfoImpl.Kind.METHOD_DOC_COPY,
158 holder.asClassDoc(), method,
159 holder.asClassDoc().isIncluded() ?
160 holder.typeName() : holder.qualifiedTypeName(),
161 false);
162 Content codelLink = HtmlTree.CODE(link);
163 Content descfrmLabel = HtmlTree.SPAN(HtmlStyle.descfrmTypeLabel, holder.asClassDoc().isClass()?
164 writer.descfrmClassLabel : writer.descfrmInterfaceLabel);
165 descfrmLabel.addContent(writer.getSpace());
166 descfrmLabel.addContent(codelLink);
167 methodDocTree.addContent(HtmlTree.DIV(HtmlStyle.block, descfrmLabel));
168 writer.addInlineComment(method, methodDocTree);
169 }
170 }
171 }
173 /**
174 * {@inheritDoc}
175 */
176 public void addTags(MethodDoc method, Content methodDocTree) {
177 writer.addTagsInfo(method, methodDocTree);
178 }
180 /**
181 * {@inheritDoc}
182 */
183 public Content getMethodDetails(Content methodDetailsTree) {
184 return getMemberTree(methodDetailsTree);
185 }
187 /**
188 * {@inheritDoc}
189 */
190 public Content getMethodDoc(Content methodDocTree,
191 boolean isLastContent) {
192 return getMemberTree(methodDocTree, isLastContent);
193 }
195 /**
196 * Close the writer.
197 */
198 public void close() throws IOException {
199 writer.close();
200 }
202 public int getMemberKind() {
203 return VisibleMemberMap.METHODS;
204 }
206 /**
207 * {@inheritDoc}
208 */
209 public void addSummaryLabel(Content memberTree) {
210 Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
211 writer.getResource("doclet.Method_Summary"));
212 memberTree.addContent(label);
213 }
215 /**
216 * {@inheritDoc}
217 */
218 public String getTableSummary() {
219 return configuration.getText("doclet.Member_Table_Summary",
220 configuration.getText("doclet.Method_Summary"),
221 configuration.getText("doclet.methods"));
222 }
224 /**
225 * {@inheritDoc}
226 */
227 public Content getCaption() {
228 return configuration.getResource("doclet.Methods");
229 }
231 /**
232 * {@inheritDoc}
233 */
234 public String[] getSummaryTableHeader(ProgramElementDoc member) {
235 String[] header = new String[] {
236 writer.getModifierTypeHeader(),
237 configuration.getText("doclet.0_and_1",
238 configuration.getText("doclet.Method"),
239 configuration.getText("doclet.Description"))
240 };
241 return header;
242 }
244 /**
245 * {@inheritDoc}
246 */
247 public void addSummaryAnchor(ClassDoc cd, Content memberTree) {
248 memberTree.addContent(writer.getMarkerAnchor(
249 SectionName.METHOD_SUMMARY));
250 }
252 /**
253 * {@inheritDoc}
254 */
255 public void addInheritedSummaryAnchor(ClassDoc cd, Content inheritedTree) {
256 inheritedTree.addContent(writer.getMarkerAnchor(
257 SectionName.METHODS_INHERITANCE, configuration.getClassName(cd)));
258 }
260 /**
261 * {@inheritDoc}
262 */
263 public void addInheritedSummaryLabel(ClassDoc cd, Content inheritedTree) {
264 Content classLink = writer.getPreQualifiedClassLink(
265 LinkInfoImpl.Kind.MEMBER, cd, false);
266 Content label = new StringContent(cd.isClass() ?
267 configuration.getText("doclet.Methods_Inherited_From_Class") :
268 configuration.getText("doclet.Methods_Inherited_From_Interface"));
269 Content labelHeading = HtmlTree.HEADING(HtmlConstants.INHERITED_SUMMARY_HEADING,
270 label);
271 labelHeading.addContent(writer.getSpace());
272 labelHeading.addContent(classLink);
273 inheritedTree.addContent(labelHeading);
274 }
276 /**
277 * {@inheritDoc}
278 */
279 protected void addSummaryType(ProgramElementDoc member, Content tdSummaryType) {
280 MethodDoc meth = (MethodDoc)member;
281 addModifierAndType(meth, meth.returnType(), tdSummaryType);
282 }
284 /**
285 * {@inheritDoc}
286 */
287 protected static void addOverridden(HtmlDocletWriter writer,
288 Type overriddenType, MethodDoc method, Content dl) {
289 if (writer.configuration.nocomment) {
290 return;
291 }
292 ClassDoc holderClassDoc = overriddenType.asClassDoc();
293 if (! (holderClassDoc.isPublic() ||
294 Util.isLinkable(holderClassDoc, writer.configuration))) {
295 //This is an implementation detail that should not be documented.
296 return;
297 }
298 if (overriddenType.asClassDoc().isIncluded() && ! method.isIncluded()) {
299 //The class is included but the method is not. That means that it
300 //is not visible so don't document this.
301 return;
302 }
303 Content label = writer.overridesLabel;
304 LinkInfoImpl.Kind context = LinkInfoImpl.Kind.METHOD_OVERRIDES;
306 if (method != null) {
307 if (overriddenType.asClassDoc().isAbstract() && method.isAbstract()){
308 //Abstract method is implemented from abstract class,
309 //not overridden
310 label = writer.specifiedByLabel;
311 context = LinkInfoImpl.Kind.METHOD_SPECIFIED_BY;
312 }
313 Content dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.overrideSpecifyLabel, label));
314 dl.addContent(dt);
315 Content overriddenTypeLink =
316 writer.getLink(new LinkInfoImpl(writer.configuration, context, overriddenType));
317 Content codeOverridenTypeLink = HtmlTree.CODE(overriddenTypeLink);
318 String name = method.name();
319 Content methlink = writer.getLink(
320 new LinkInfoImpl(writer.configuration, LinkInfoImpl.Kind.MEMBER,
321 overriddenType.asClassDoc())
322 .where(writer.getName(writer.getAnchor(method))).label(name));
323 Content codeMethLink = HtmlTree.CODE(methlink);
324 Content dd = HtmlTree.DD(codeMethLink);
325 dd.addContent(writer.getSpace());
326 dd.addContent(writer.getResource("doclet.in_class"));
327 dd.addContent(writer.getSpace());
328 dd.addContent(codeOverridenTypeLink);
329 dl.addContent(dd);
330 }
331 }
333 /**
334 * Parse the <Code> tag and return the text.
335 */
336 protected String parseCodeTag(String tag){
337 if(tag == null){
338 return "";
339 }
341 String lc = tag.toLowerCase();
342 int begin = lc.indexOf("<code>");
343 int end = lc.indexOf("</code>");
344 if(begin == -1 || end == -1 || end <= begin){
345 return tag;
346 } else {
347 return tag.substring(begin + 6, end);
348 }
349 }
351 /**
352 * {@inheritDoc}
353 */
354 protected static void addImplementsInfo(HtmlDocletWriter writer,
355 MethodDoc method, Content dl) {
356 if(writer.configuration.nocomment){
357 return;
358 }
359 ImplementedMethods implementedMethodsFinder =
360 new ImplementedMethods(method, writer.configuration);
361 MethodDoc[] implementedMethods = implementedMethodsFinder.build();
362 for (int i = 0; i < implementedMethods.length; i++) {
363 MethodDoc implementedMeth = implementedMethods[i];
364 Type intfac = implementedMethodsFinder.getMethodHolder(implementedMeth);
365 Content intfaclink = writer.getLink(new LinkInfoImpl(
366 writer.configuration, LinkInfoImpl.Kind.METHOD_SPECIFIED_BY, intfac));
367 Content codeIntfacLink = HtmlTree.CODE(intfaclink);
368 Content dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.overrideSpecifyLabel, writer.specifiedByLabel));
369 dl.addContent(dt);
370 Content methlink = writer.getDocLink(
371 LinkInfoImpl.Kind.MEMBER, implementedMeth,
372 implementedMeth.name(), false);
373 Content codeMethLink = HtmlTree.CODE(methlink);
374 Content dd = HtmlTree.DD(codeMethLink);
375 dd.addContent(writer.getSpace());
376 dd.addContent(writer.getResource("doclet.in_interface"));
377 dd.addContent(writer.getSpace());
378 dd.addContent(codeIntfacLink);
379 dl.addContent(dd);
380 }
381 }
383 /**
384 * Add the return type.
385 *
386 * @param method the method being documented.
387 * @param htmltree the content tree to which the return type will be added
388 */
389 protected void addReturnType(MethodDoc method, Content htmltree) {
390 Type type = method.returnType();
391 if (type != null) {
392 Content linkContent = writer.getLink(
393 new LinkInfoImpl(configuration, LinkInfoImpl.Kind.RETURN_TYPE, type));
394 htmltree.addContent(linkContent);
395 htmltree.addContent(writer.getSpace());
396 }
397 }
399 /**
400 * {@inheritDoc}
401 */
402 protected Content getNavSummaryLink(ClassDoc cd, boolean link) {
403 if (link) {
404 if (cd == null) {
405 return writer.getHyperLink(
406 SectionName.METHOD_SUMMARY,
407 writer.getResource("doclet.navMethod"));
408 } else {
409 return writer.getHyperLink(
410 SectionName.METHODS_INHERITANCE,
411 configuration.getClassName(cd), writer.getResource("doclet.navMethod"));
412 }
413 } else {
414 return writer.getResource("doclet.navMethod");
415 }
416 }
418 /**
419 * {@inheritDoc}
420 */
421 protected void addNavDetailLink(boolean link, Content liNav) {
422 if (link) {
423 liNav.addContent(writer.getHyperLink(
424 SectionName.METHOD_DETAIL, writer.getResource("doclet.navMethod")));
425 } else {
426 liNav.addContent(writer.getResource("doclet.navMethod"));
427 }
428 }
429 }