Tue, 14 May 2013 10:14:54 -0700
8012176: reduce use of TagletOutputImpl.toString
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1998, 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.*;
29 import java.text.SimpleDateFormat;
30 import java.util.*;
32 import com.sun.javadoc.*;
33 import com.sun.tools.doclets.formats.html.markup.*;
34 import com.sun.tools.doclets.internal.toolkit.*;
35 import com.sun.tools.doclets.internal.toolkit.taglets.*;
36 import com.sun.tools.doclets.internal.toolkit.util.*;
38 /**
39 * Class for the Html Format Code Generation specific to JavaDoc.
40 * This Class contains methods related to the Html Code Generation which
41 * are used extensively while generating the entire documentation.
42 *
43 * <p><b>This is NOT part of any supported API.
44 * If you write code that depends on this, you do so at your own risk.
45 * This code and its internal interfaces are subject to change or
46 * deletion without notice.</b>
47 *
48 * @since 1.2
49 * @author Atul M Dambalkar
50 * @author Robert Field
51 * @author Bhavesh Patel (Modified)
52 */
53 public class HtmlDocletWriter extends HtmlDocWriter {
55 /**
56 * Relative path from the file getting generated to the destination
57 * directory. For example, if the file getting generated is
58 * "java/lang/Object.html", then the path to the root is "../..".
59 * This string can be empty if the file getting generated is in
60 * the destination directory.
61 */
62 public final DocPath pathToRoot;
64 /**
65 * Platform-independent path from the current or the
66 * destination directory to the file getting generated.
67 * Used when creating the file.
68 */
69 public final DocPath path;
71 /**
72 * Name of the file getting generated. If the file getting generated is
73 * "java/lang/Object.html", then the filename is "Object.html".
74 */
75 public final DocPath filename;
77 /**
78 * The global configuration information for this run.
79 */
80 public final ConfigurationImpl configuration;
82 /**
83 * To check whether annotation heading is printed or not.
84 */
85 protected boolean printedAnnotationHeading = false;
87 /**
88 * To check whether the repeated annotations is documented or not.
89 */
90 private boolean isAnnotationDocumented = false;
92 /**
93 * To check whether the container annotations is documented or not.
94 */
95 private boolean isContainerDocumented = false;
97 /**
98 * Constructor to construct the HtmlStandardWriter object.
99 *
100 * @param path File to be generated.
101 */
102 public HtmlDocletWriter(ConfigurationImpl configuration, DocPath path)
103 throws IOException {
104 super(configuration, path);
105 this.configuration = configuration;
106 this.path = path;
107 this.pathToRoot = path.parent().invert();
108 this.filename = path.basename();
109 }
111 /**
112 * Replace {@docRoot} tag used in options that accept HTML text, such
113 * as -header, -footer, -top and -bottom, and when converting a relative
114 * HREF where commentTagsToString inserts a {@docRoot} where one was
115 * missing. (Also see DocRootTaglet for {@docRoot} tags in doc
116 * comments.)
117 * <p>
118 * Replace {@docRoot} tag in htmlstr with the relative path to the
119 * destination directory from the directory where the file is being
120 * written, looping to handle all such tags in htmlstr.
121 * <p>
122 * For example, for "-d docs" and -header containing {@docRoot}, when
123 * the HTML page for source file p/C1.java is being generated, the
124 * {@docRoot} tag would be inserted into the header as "../",
125 * the relative path from docs/p/ to docs/ (the document root).
126 * <p>
127 * Note: This doc comment was written with '&#064;' representing '@'
128 * to prevent the inline tag from being interpreted.
129 */
130 public String replaceDocRootDir(String htmlstr) {
131 // Return if no inline tags exist
132 int index = htmlstr.indexOf("{@");
133 if (index < 0) {
134 return htmlstr;
135 }
136 String lowerHtml = htmlstr.toLowerCase();
137 // Return index of first occurrence of {@docroot}
138 // Note: {@docRoot} is not case sensitive when passed in w/command line option
139 index = lowerHtml.indexOf("{@docroot}", index);
140 if (index < 0) {
141 return htmlstr;
142 }
143 StringBuilder buf = new StringBuilder();
144 int previndex = 0;
145 while (true) {
146 if (configuration.docrootparent.length() > 0) {
147 final String docroot_parent = "{@docroot}/..";
148 // Search for lowercase version of {@docRoot}/..
149 index = lowerHtml.indexOf(docroot_parent, previndex);
150 // If next {@docRoot}/.. pattern not found, append rest of htmlstr and exit loop
151 if (index < 0) {
152 buf.append(htmlstr.substring(previndex));
153 break;
154 }
155 // If next {@docroot}/.. pattern found, append htmlstr up to start of tag
156 buf.append(htmlstr.substring(previndex, index));
157 previndex = index + docroot_parent.length();
158 // Insert docrootparent absolute path where {@docRoot}/.. was located
160 buf.append(configuration.docrootparent);
161 // Append slash if next character is not a slash
162 if (previndex < htmlstr.length() && htmlstr.charAt(previndex) != '/') {
163 buf.append('/');
164 }
165 } else {
166 final String docroot = "{@docroot}";
167 // Search for lowercase version of {@docRoot}
168 index = lowerHtml.indexOf(docroot, previndex);
169 // If next {@docRoot} tag not found, append rest of htmlstr and exit loop
170 if (index < 0) {
171 buf.append(htmlstr.substring(previndex));
172 break;
173 }
174 // If next {@docroot} tag found, append htmlstr up to start of tag
175 buf.append(htmlstr.substring(previndex, index));
176 previndex = index + docroot.length();
177 // Insert relative path where {@docRoot} was located
178 buf.append(pathToRoot.isEmpty() ? "." : pathToRoot.getPath());
179 // Append slash if next character is not a slash
180 if (previndex < htmlstr.length() && htmlstr.charAt(previndex) != '/') {
181 buf.append('/');
182 }
183 }
184 }
185 return buf.toString();
186 }
188 /**
189 * Get the script to show or hide the All classes link.
190 *
191 * @param id id of the element to show or hide
192 * @return a content tree for the script
193 */
194 public Content getAllClassesLinkScript(String id) {
195 HtmlTree script = new HtmlTree(HtmlTag.SCRIPT);
196 script.addAttr(HtmlAttr.TYPE, "text/javascript");
197 String scriptCode = "<!--" + DocletConstants.NL +
198 " allClassesLink = document.getElementById(\"" + id + "\");" + DocletConstants.NL +
199 " if(window==top) {" + DocletConstants.NL +
200 " allClassesLink.style.display = \"block\";" + DocletConstants.NL +
201 " }" + DocletConstants.NL +
202 " else {" + DocletConstants.NL +
203 " allClassesLink.style.display = \"none\";" + DocletConstants.NL +
204 " }" + DocletConstants.NL +
205 " //-->" + DocletConstants.NL;
206 Content scriptContent = new RawHtml(scriptCode);
207 script.addContent(scriptContent);
208 Content div = HtmlTree.DIV(script);
209 return div;
210 }
212 /**
213 * Add method information.
214 *
215 * @param method the method to be documented
216 * @param dl the content tree to which the method information will be added
217 */
218 private void addMethodInfo(MethodDoc method, Content dl) {
219 ClassDoc[] intfacs = method.containingClass().interfaces();
220 MethodDoc overriddenMethod = method.overriddenMethod();
221 // Check whether there is any implementation or overridden info to be
222 // printed. If no overridden or implementation info needs to be
223 // printed, do not print this section.
224 if ((intfacs.length > 0 &&
225 new ImplementedMethods(method, this.configuration).build().length > 0) ||
226 overriddenMethod != null) {
227 MethodWriterImpl.addImplementsInfo(this, method, dl);
228 if (overriddenMethod != null) {
229 MethodWriterImpl.addOverridden(this,
230 method.overriddenType(), overriddenMethod, dl);
231 }
232 }
233 }
235 /**
236 * Adds the tags information.
237 *
238 * @param doc the doc for which the tags will be generated
239 * @param htmltree the documentation tree to which the tags will be added
240 */
241 protected void addTagsInfo(Doc doc, Content htmltree) {
242 if (configuration.nocomment) {
243 return;
244 }
245 Content dl = new HtmlTree(HtmlTag.DL);
246 if (doc instanceof MethodDoc) {
247 addMethodInfo((MethodDoc) doc, dl);
248 }
249 TagletOutputImpl output = new TagletOutputImpl();
250 TagletWriter.genTagOuput(configuration.tagletManager, doc,
251 configuration.tagletManager.getCustomTags(doc),
252 getTagletWriterInstance(false), output);
253 dl.addContent(output.getContent());
254 htmltree.addContent(dl);
255 }
257 /**
258 * Check whether there are any tags for Serialization Overview
259 * section to be printed.
260 *
261 * @param field the FieldDoc object to check for tags.
262 * @return true if there are tags to be printed else return false.
263 */
264 protected boolean hasSerializationOverviewTags(FieldDoc field) {
265 TagletOutputImpl output = new TagletOutputImpl();
266 TagletWriter.genTagOuput(configuration.tagletManager, field,
267 configuration.tagletManager.getCustomTags(field),
268 getTagletWriterInstance(false), output);
269 return !output.getContent().isEmpty();
270 }
272 /**
273 * Returns a TagletWriter that knows how to write HTML.
274 *
275 * @return a TagletWriter that knows how to write HTML.
276 */
277 public TagletWriter getTagletWriterInstance(boolean isFirstSentence) {
278 return new TagletWriterImpl(this, isFirstSentence);
279 }
281 /**
282 * Get Package link, with target frame.
283 *
284 * @param pd The link will be to the "package-summary.html" page for this package
285 * @param target name of the target frame
286 * @param label tag for the link
287 * @return a content for the target package link
288 */
289 public Content getTargetPackageLink(PackageDoc pd, String target,
290 Content label) {
291 return getHyperLink(pathString(pd, DocPaths.PACKAGE_SUMMARY), label, "", target);
292 }
294 /**
295 * Get Profile Package link, with target frame.
296 *
297 * @param pd the packageDoc object
298 * @param target name of the target frame
299 * @param label tag for the link
300 * @param profileName the name of the profile being documented
301 * @return a content for the target profile packages link
302 */
303 public Content getTargetProfilePackageLink(PackageDoc pd, String target,
304 Content label, String profileName) {
305 return getHyperLink(pathString(pd, DocPaths.profilePackageSummary(profileName)),
306 label, "", target);
307 }
309 /**
310 * Get Profile link, with target frame.
311 *
312 * @param target name of the target frame
313 * @param label tag for the link
314 * @param profileName the name of the profile being documented
315 * @return a content for the target profile link
316 */
317 public Content getTargetProfileLink(String target, Content label,
318 String profileName) {
319 return getHyperLink(pathToRoot.resolve(
320 DocPaths.profileSummary(profileName)), label, "", target);
321 }
323 /**
324 * Get the type name for profile search.
325 *
326 * @param cd the classDoc object for which the type name conversion is needed
327 * @return a type name string for the type
328 */
329 public String getTypeNameForProfile(ClassDoc cd) {
330 StringBuilder typeName =
331 new StringBuilder((cd.containingPackage()).name().replace(".", "/"));
332 typeName.append("/")
333 .append(cd.name().replace(".", "$"));
334 return typeName.toString();
335 }
337 /**
338 * Check if a type belongs to a profile.
339 *
340 * @param cd the classDoc object that needs to be checked
341 * @param profileValue the profile in which the type needs to be checked
342 * @return true if the type is in the profile
343 */
344 public boolean isTypeInProfile(ClassDoc cd, int profileValue) {
345 return (configuration.profiles.getProfile(getTypeNameForProfile(cd)) <= profileValue);
346 }
348 public void addClassesSummary(ClassDoc[] classes, String label,
349 String tableSummary, String[] tableHeader, Content summaryContentTree,
350 int profileValue) {
351 if(classes.length > 0) {
352 Arrays.sort(classes);
353 Content caption = getTableCaption(label);
354 Content table = HtmlTree.TABLE(HtmlStyle.packageSummary, 0, 3, 0,
355 tableSummary, caption);
356 table.addContent(getSummaryTableHeader(tableHeader, "col"));
357 Content tbody = new HtmlTree(HtmlTag.TBODY);
358 for (int i = 0; i < classes.length; i++) {
359 if (!isTypeInProfile(classes[i], profileValue)) {
360 continue;
361 }
362 if (!Util.isCoreClass(classes[i]) ||
363 !configuration.isGeneratedDoc(classes[i])) {
364 continue;
365 }
366 Content classContent = getLink(new LinkInfoImpl(
367 configuration, LinkInfoImpl.Kind.PACKAGE, classes[i]));
368 Content tdClass = HtmlTree.TD(HtmlStyle.colFirst, classContent);
369 HtmlTree tr = HtmlTree.TR(tdClass);
370 if (i%2 == 0)
371 tr.addStyle(HtmlStyle.altColor);
372 else
373 tr.addStyle(HtmlStyle.rowColor);
374 HtmlTree tdClassDescription = new HtmlTree(HtmlTag.TD);
375 tdClassDescription.addStyle(HtmlStyle.colLast);
376 if (Util.isDeprecated(classes[i])) {
377 tdClassDescription.addContent(deprecatedLabel);
378 if (classes[i].tags("deprecated").length > 0) {
379 addSummaryDeprecatedComment(classes[i],
380 classes[i].tags("deprecated")[0], tdClassDescription);
381 }
382 }
383 else
384 addSummaryComment(classes[i], tdClassDescription);
385 tr.addContent(tdClassDescription);
386 tbody.addContent(tr);
387 }
388 table.addContent(tbody);
389 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
390 summaryContentTree.addContent(li);
391 }
392 }
394 /**
395 * Generates the HTML document tree and prints it out.
396 *
397 * @param metakeywords Array of String keywords for META tag. Each element
398 * of the array is assigned to a separate META tag.
399 * Pass in null for no array
400 * @param includeScript true if printing windowtitle script
401 * false for files that appear in the left-hand frames
402 * @param body the body htmltree to be included in the document
403 */
404 public void printHtmlDocument(String[] metakeywords, boolean includeScript,
405 Content body) throws IOException {
406 Content htmlDocType = DocType.TRANSITIONAL;
407 Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
408 Content head = new HtmlTree(HtmlTag.HEAD);
409 if (!configuration.notimestamp) {
410 Content headComment = new Comment(getGeneratedByString());
411 head.addContent(headComment);
412 }
413 if (configuration.charset.length() > 0) {
414 Content meta = HtmlTree.META("Content-Type", "text/html",
415 configuration.charset);
416 head.addContent(meta);
417 }
418 head.addContent(getTitle());
419 if (!configuration.notimestamp) {
420 SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
421 Content meta = HtmlTree.META("date", dateFormat.format(new Date()));
422 head.addContent(meta);
423 }
424 if (metakeywords != null) {
425 for (int i=0; i < metakeywords.length; i++) {
426 Content meta = HtmlTree.META("keywords", metakeywords[i]);
427 head.addContent(meta);
428 }
429 }
430 head.addContent(getStyleSheetProperties());
431 head.addContent(getScriptProperties());
432 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
433 head, body);
434 Content htmlDocument = new HtmlDocument(htmlDocType,
435 htmlComment, htmlTree);
436 write(htmlDocument);
437 }
439 /**
440 * Get the window title.
441 *
442 * @param title the title string to construct the complete window title
443 * @return the window title string
444 */
445 public String getWindowTitle(String title) {
446 if (configuration.windowtitle.length() > 0) {
447 title += " (" + configuration.windowtitle + ")";
448 }
449 return title;
450 }
452 /**
453 * Get user specified header and the footer.
454 *
455 * @param header if true print the user provided header else print the
456 * user provided footer.
457 */
458 public Content getUserHeaderFooter(boolean header) {
459 String content;
460 if (header) {
461 content = replaceDocRootDir(configuration.header);
462 } else {
463 if (configuration.footer.length() != 0) {
464 content = replaceDocRootDir(configuration.footer);
465 } else {
466 content = replaceDocRootDir(configuration.header);
467 }
468 }
469 Content rawContent = new RawHtml(content);
470 Content em = HtmlTree.EM(rawContent);
471 return em;
472 }
474 /**
475 * Adds the user specified top.
476 *
477 * @param body the content tree to which user specified top will be added
478 */
479 public void addTop(Content body) {
480 Content top = new RawHtml(replaceDocRootDir(configuration.top));
481 body.addContent(top);
482 }
484 /**
485 * Adds the user specified bottom.
486 *
487 * @param body the content tree to which user specified bottom will be added
488 */
489 public void addBottom(Content body) {
490 Content bottom = new RawHtml(replaceDocRootDir(configuration.bottom));
491 Content small = HtmlTree.SMALL(bottom);
492 Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
493 body.addContent(p);
494 }
496 /**
497 * Adds the navigation bar for the Html page at the top and and the bottom.
498 *
499 * @param header If true print navigation bar at the top of the page else
500 * @param body the HtmlTree to which the nav links will be added
501 */
502 protected void addNavLinks(boolean header, Content body) {
503 if (!configuration.nonavbar) {
504 String allClassesId = "allclasses_";
505 HtmlTree navDiv = new HtmlTree(HtmlTag.DIV);
506 if (header) {
507 body.addContent(HtmlConstants.START_OF_TOP_NAVBAR);
508 navDiv.addStyle(HtmlStyle.topNav);
509 allClassesId += "navbar_top";
510 Content a = getMarkerAnchor("navbar_top");
511 navDiv.addContent(a);
512 Content skipLinkContent = getHyperLink(DocLink.fragment("skip-navbar_top"),
513 HtmlTree.EMPTY,
514 configuration.getText("doclet.Skip_navigation_links"),
515 "");
516 navDiv.addContent(skipLinkContent);
517 } else {
518 body.addContent(HtmlConstants.START_OF_BOTTOM_NAVBAR);
519 navDiv.addStyle(HtmlStyle.bottomNav);
520 allClassesId += "navbar_bottom";
521 Content a = getMarkerAnchor("navbar_bottom");
522 navDiv.addContent(a);
523 Content skipLinkContent = getHyperLink(DocLink.fragment("skip-navbar_bottom"),
524 HtmlTree.EMPTY,
525 configuration.getText("doclet.Skip_navigation_links"),
526 "");
527 navDiv.addContent(skipLinkContent);
528 }
529 if (header) {
530 navDiv.addContent(getMarkerAnchor("navbar_top_firstrow"));
531 } else {
532 navDiv.addContent(getMarkerAnchor("navbar_bottom_firstrow"));
533 }
534 HtmlTree navList = new HtmlTree(HtmlTag.UL);
535 navList.addStyle(HtmlStyle.navList);
536 navList.addAttr(HtmlAttr.TITLE,
537 configuration.getText("doclet.Navigation"));
538 if (configuration.createoverview) {
539 navList.addContent(getNavLinkContents());
540 }
541 if (configuration.packages.length == 1) {
542 navList.addContent(getNavLinkPackage(configuration.packages[0]));
543 } else if (configuration.packages.length > 1) {
544 navList.addContent(getNavLinkPackage());
545 }
546 navList.addContent(getNavLinkClass());
547 if(configuration.classuse) {
548 navList.addContent(getNavLinkClassUse());
549 }
550 if(configuration.createtree) {
551 navList.addContent(getNavLinkTree());
552 }
553 if(!(configuration.nodeprecated ||
554 configuration.nodeprecatedlist)) {
555 navList.addContent(getNavLinkDeprecated());
556 }
557 if(configuration.createindex) {
558 navList.addContent(getNavLinkIndex());
559 }
560 if (!configuration.nohelp) {
561 navList.addContent(getNavLinkHelp());
562 }
563 navDiv.addContent(navList);
564 Content aboutDiv = HtmlTree.DIV(HtmlStyle.aboutLanguage, getUserHeaderFooter(header));
565 navDiv.addContent(aboutDiv);
566 body.addContent(navDiv);
567 Content ulNav = HtmlTree.UL(HtmlStyle.navList, getNavLinkPrevious());
568 ulNav.addContent(getNavLinkNext());
569 Content subDiv = HtmlTree.DIV(HtmlStyle.subNav, ulNav);
570 Content ulFrames = HtmlTree.UL(HtmlStyle.navList, getNavShowLists());
571 ulFrames.addContent(getNavHideLists(filename));
572 subDiv.addContent(ulFrames);
573 HtmlTree ulAllClasses = HtmlTree.UL(HtmlStyle.navList, getNavLinkClassIndex());
574 ulAllClasses.addAttr(HtmlAttr.ID, allClassesId.toString());
575 subDiv.addContent(ulAllClasses);
576 subDiv.addContent(getAllClassesLinkScript(allClassesId.toString()));
577 addSummaryDetailLinks(subDiv);
578 if (header) {
579 subDiv.addContent(getMarkerAnchor("skip-navbar_top"));
580 body.addContent(subDiv);
581 body.addContent(HtmlConstants.END_OF_TOP_NAVBAR);
582 } else {
583 subDiv.addContent(getMarkerAnchor("skip-navbar_bottom"));
584 body.addContent(subDiv);
585 body.addContent(HtmlConstants.END_OF_BOTTOM_NAVBAR);
586 }
587 }
588 }
590 /**
591 * Get the word "NEXT" to indicate that no link is available. Override
592 * this method to customize next link.
593 *
594 * @return a content tree for the link
595 */
596 protected Content getNavLinkNext() {
597 return getNavLinkNext(null);
598 }
600 /**
601 * Get the word "PREV" to indicate that no link is available. Override
602 * this method to customize prev link.
603 *
604 * @return a content tree for the link
605 */
606 protected Content getNavLinkPrevious() {
607 return getNavLinkPrevious(null);
608 }
610 /**
611 * Do nothing. This is the default method.
612 */
613 protected void addSummaryDetailLinks(Content navDiv) {
614 }
616 /**
617 * Get link to the "overview-summary.html" page.
618 *
619 * @return a content tree for the link
620 */
621 protected Content getNavLinkContents() {
622 Content linkContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_SUMMARY),
623 overviewLabel, "", "");
624 Content li = HtmlTree.LI(linkContent);
625 return li;
626 }
628 /**
629 * Get link to the "package-summary.html" page for the package passed.
630 *
631 * @param pkg Package to which link will be generated
632 * @return a content tree for the link
633 */
634 protected Content getNavLinkPackage(PackageDoc pkg) {
635 Content linkContent = getPackageLink(pkg,
636 packageLabel);
637 Content li = HtmlTree.LI(linkContent);
638 return li;
639 }
641 /**
642 * Get the word "Package" , to indicate that link is not available here.
643 *
644 * @return a content tree for the link
645 */
646 protected Content getNavLinkPackage() {
647 Content li = HtmlTree.LI(packageLabel);
648 return li;
649 }
651 /**
652 * Get the word "Use", to indicate that link is not available.
653 *
654 * @return a content tree for the link
655 */
656 protected Content getNavLinkClassUse() {
657 Content li = HtmlTree.LI(useLabel);
658 return li;
659 }
661 /**
662 * Get link for previous file.
663 *
664 * @param prev File name for the prev link
665 * @return a content tree for the link
666 */
667 public Content getNavLinkPrevious(DocPath prev) {
668 Content li;
669 if (prev != null) {
670 li = HtmlTree.LI(getHyperLink(prev, prevLabel, "", ""));
671 }
672 else
673 li = HtmlTree.LI(prevLabel);
674 return li;
675 }
677 /**
678 * Get link for next file. If next is null, just print the label
679 * without linking it anywhere.
680 *
681 * @param next File name for the next link
682 * @return a content tree for the link
683 */
684 public Content getNavLinkNext(DocPath next) {
685 Content li;
686 if (next != null) {
687 li = HtmlTree.LI(getHyperLink(next, nextLabel, "", ""));
688 }
689 else
690 li = HtmlTree.LI(nextLabel);
691 return li;
692 }
694 /**
695 * Get "FRAMES" link, to switch to the frame version of the output.
696 *
697 * @param link File to be linked, "index.html"
698 * @return a content tree for the link
699 */
700 protected Content getNavShowLists(DocPath link) {
701 DocLink dl = new DocLink(link, path.getPath(), null);
702 Content framesContent = getHyperLink(dl, framesLabel, "", "_top");
703 Content li = HtmlTree.LI(framesContent);
704 return li;
705 }
707 /**
708 * Get "FRAMES" link, to switch to the frame version of the output.
709 *
710 * @return a content tree for the link
711 */
712 protected Content getNavShowLists() {
713 return getNavShowLists(pathToRoot.resolve(DocPaths.INDEX));
714 }
716 /**
717 * Get "NO FRAMES" link, to switch to the non-frame version of the output.
718 *
719 * @param link File to be linked
720 * @return a content tree for the link
721 */
722 protected Content getNavHideLists(DocPath link) {
723 Content noFramesContent = getHyperLink(link, noframesLabel, "", "_top");
724 Content li = HtmlTree.LI(noFramesContent);
725 return li;
726 }
728 /**
729 * Get "Tree" link in the navigation bar. If there is only one package
730 * specified on the command line, then the "Tree" link will be to the
731 * only "package-tree.html" file otherwise it will be to the
732 * "overview-tree.html" file.
733 *
734 * @return a content tree for the link
735 */
736 protected Content getNavLinkTree() {
737 Content treeLinkContent;
738 PackageDoc[] packages = configuration.root.specifiedPackages();
739 if (packages.length == 1 && configuration.root.specifiedClasses().length == 0) {
740 treeLinkContent = getHyperLink(pathString(packages[0],
741 DocPaths.PACKAGE_TREE), treeLabel,
742 "", "");
743 } else {
744 treeLinkContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
745 treeLabel, "", "");
746 }
747 Content li = HtmlTree.LI(treeLinkContent);
748 return li;
749 }
751 /**
752 * Get the overview tree link for the main tree.
753 *
754 * @param label the label for the link
755 * @return a content tree for the link
756 */
757 protected Content getNavLinkMainTree(String label) {
758 Content mainTreeContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
759 new StringContent(label));
760 Content li = HtmlTree.LI(mainTreeContent);
761 return li;
762 }
764 /**
765 * Get the word "Class", to indicate that class link is not available.
766 *
767 * @return a content tree for the link
768 */
769 protected Content getNavLinkClass() {
770 Content li = HtmlTree.LI(classLabel);
771 return li;
772 }
774 /**
775 * Get "Deprecated" API link in the navigation bar.
776 *
777 * @return a content tree for the link
778 */
779 protected Content getNavLinkDeprecated() {
780 Content linkContent = getHyperLink(pathToRoot.resolve(DocPaths.DEPRECATED_LIST),
781 deprecatedLabel, "", "");
782 Content li = HtmlTree.LI(linkContent);
783 return li;
784 }
786 /**
787 * Get link for generated index. If the user has used "-splitindex"
788 * command line option, then link to file "index-files/index-1.html" is
789 * generated otherwise link to file "index-all.html" is generated.
790 *
791 * @return a content tree for the link
792 */
793 protected Content getNavLinkClassIndex() {
794 Content allClassesContent = getHyperLink(pathToRoot.resolve(
795 DocPaths.ALLCLASSES_NOFRAME),
796 allclassesLabel, "", "");
797 Content li = HtmlTree.LI(allClassesContent);
798 return li;
799 }
801 /**
802 * Get link for generated class index.
803 *
804 * @return a content tree for the link
805 */
806 protected Content getNavLinkIndex() {
807 Content linkContent = getHyperLink(pathToRoot.resolve(
808 (configuration.splitindex
809 ? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
810 : DocPaths.INDEX_ALL)),
811 indexLabel, "", "");
812 Content li = HtmlTree.LI(linkContent);
813 return li;
814 }
816 /**
817 * Get help file link. If user has provided a help file, then generate a
818 * link to the user given file, which is already copied to current or
819 * destination directory.
820 *
821 * @return a content tree for the link
822 */
823 protected Content getNavLinkHelp() {
824 String helpfile = configuration.helpfile;
825 DocPath helpfilenm;
826 if (helpfile.isEmpty()) {
827 helpfilenm = DocPaths.HELP_DOC;
828 } else {
829 DocFile file = DocFile.createFileForInput(configuration, helpfile);
830 helpfilenm = DocPath.create(file.getName());
831 }
832 Content linkContent = getHyperLink(pathToRoot.resolve(helpfilenm),
833 helpLabel, "", "");
834 Content li = HtmlTree.LI(linkContent);
835 return li;
836 }
838 /**
839 * Get summary table header.
840 *
841 * @param header the header for the table
842 * @param scope the scope of the headers
843 * @return a content tree for the header
844 */
845 public Content getSummaryTableHeader(String[] header, String scope) {
846 Content tr = new HtmlTree(HtmlTag.TR);
847 int size = header.length;
848 Content tableHeader;
849 if (size == 1) {
850 tableHeader = new StringContent(header[0]);
851 tr.addContent(HtmlTree.TH(HtmlStyle.colOne, scope, tableHeader));
852 return tr;
853 }
854 for (int i = 0; i < size; i++) {
855 tableHeader = new StringContent(header[i]);
856 if(i == 0)
857 tr.addContent(HtmlTree.TH(HtmlStyle.colFirst, scope, tableHeader));
858 else if(i == (size - 1))
859 tr.addContent(HtmlTree.TH(HtmlStyle.colLast, scope, tableHeader));
860 else
861 tr.addContent(HtmlTree.TH(scope, tableHeader));
862 }
863 return tr;
864 }
866 /**
867 * Get table caption.
868 *
869 * @param rawText the caption for the table which could be raw Html
870 * @return a content tree for the caption
871 */
872 public Content getTableCaption(String rawText) {
873 Content title = new RawHtml(rawText);
874 Content captionSpan = HtmlTree.SPAN(title);
875 Content space = getSpace();
876 Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, space);
877 Content caption = HtmlTree.CAPTION(captionSpan);
878 caption.addContent(tabSpan);
879 return caption;
880 }
882 /**
883 * Get the marker anchor which will be added to the documentation tree.
884 *
885 * @param anchorName the anchor name attribute
886 * @return a content tree for the marker anchor
887 */
888 public Content getMarkerAnchor(String anchorName) {
889 return getMarkerAnchor(anchorName, null);
890 }
892 /**
893 * Get the marker anchor which will be added to the documentation tree.
894 *
895 * @param anchorName the anchor name attribute
896 * @param anchorContent the content that should be added to the anchor
897 * @return a content tree for the marker anchor
898 */
899 public Content getMarkerAnchor(String anchorName, Content anchorContent) {
900 if (anchorContent == null)
901 anchorContent = new Comment(" ");
902 Content markerAnchor = HtmlTree.A_NAME(anchorName, anchorContent);
903 return markerAnchor;
904 }
906 /**
907 * Returns a packagename content.
908 *
909 * @param packageDoc the package to check
910 * @return package name content
911 */
912 public Content getPackageName(PackageDoc packageDoc) {
913 return packageDoc == null || packageDoc.name().length() == 0 ?
914 defaultPackageLabel :
915 getPackageLabel(packageDoc.name());
916 }
918 /**
919 * Returns a package name label.
920 *
921 * @param packageName the package name
922 * @return the package name content
923 */
924 public Content getPackageLabel(String packageName) {
925 return new StringContent(packageName);
926 }
928 /**
929 * Add package deprecation information to the documentation tree
930 *
931 * @param deprPkgs list of deprecated packages
932 * @param headingKey the caption for the deprecated package table
933 * @param tableSummary the summary for the deprecated package table
934 * @param tableHeader table headers for the deprecated package table
935 * @param contentTree the content tree to which the deprecated package table will be added
936 */
937 protected void addPackageDeprecatedAPI(List<Doc> deprPkgs, String headingKey,
938 String tableSummary, String[] tableHeader, Content contentTree) {
939 if (deprPkgs.size() > 0) {
940 Content table = HtmlTree.TABLE(0, 3, 0, tableSummary,
941 getTableCaption(configuration.getText(headingKey)));
942 table.addContent(getSummaryTableHeader(tableHeader, "col"));
943 Content tbody = new HtmlTree(HtmlTag.TBODY);
944 for (int i = 0; i < deprPkgs.size(); i++) {
945 PackageDoc pkg = (PackageDoc) deprPkgs.get(i);
946 HtmlTree td = HtmlTree.TD(HtmlStyle.colOne,
947 getPackageLink(pkg, getPackageName(pkg)));
948 if (pkg.tags("deprecated").length > 0) {
949 addInlineDeprecatedComment(pkg, pkg.tags("deprecated")[0], td);
950 }
951 HtmlTree tr = HtmlTree.TR(td);
952 if (i % 2 == 0) {
953 tr.addStyle(HtmlStyle.altColor);
954 } else {
955 tr.addStyle(HtmlStyle.rowColor);
956 }
957 tbody.addContent(tr);
958 }
959 table.addContent(tbody);
960 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
961 Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
962 contentTree.addContent(ul);
963 }
964 }
966 /**
967 * Return the path to the class page for a classdoc.
968 *
969 * @param cd Class to which the path is requested.
970 * @param name Name of the file(doesn't include path).
971 */
972 protected DocPath pathString(ClassDoc cd, DocPath name) {
973 return pathString(cd.containingPackage(), name);
974 }
976 /**
977 * Return path to the given file name in the given package. So if the name
978 * passed is "Object.html" and the name of the package is "java.lang", and
979 * if the relative path is "../.." then returned string will be
980 * "../../java/lang/Object.html"
981 *
982 * @param pd Package in which the file name is assumed to be.
983 * @param name File name, to which path string is.
984 */
985 protected DocPath pathString(PackageDoc pd, DocPath name) {
986 return pathToRoot.resolve(DocPath.forPackage(pd).resolve(name));
987 }
989 /**
990 * Return the link to the given package.
991 *
992 * @param pkg the package to link to.
993 * @param label the label for the link.
994 * @param isStrong true if the label should be strong.
995 * @return the link to the given package.
996 */
997 public String getPackageLinkString(PackageDoc pkg, String label,
998 boolean isStrong) {
999 return getPackageLinkString(pkg, label, isStrong, "");
1000 }
1002 /**
1003 * Return the link to the given package.
1004 *
1005 * @param pkg the package to link to.
1006 * @param label the label for the link.
1007 * @param isStrong true if the label should be strong.
1008 * @param style the font of the package link label.
1009 * @return the link to the given package.
1010 */
1011 public String getPackageLinkString(PackageDoc pkg, String label, boolean isStrong,
1012 String style) {
1013 boolean included = pkg != null && pkg.isIncluded();
1014 if (! included) {
1015 PackageDoc[] packages = configuration.packages;
1016 for (int i = 0; i < packages.length; i++) {
1017 if (packages[i].equals(pkg)) {
1018 included = true;
1019 break;
1020 }
1021 }
1022 }
1023 if (included || pkg == null) {
1024 return getHyperLinkString(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
1025 label, isStrong, style);
1026 } else {
1027 DocLink crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
1028 if (crossPkgLink != null) {
1029 return getHyperLinkString(crossPkgLink, label, isStrong, style);
1030 } else {
1031 return label;
1032 }
1033 }
1034 }
1036 /**
1037 * Return the link to the given package.
1038 *
1039 * @param pkg the package to link to.
1040 * @param label the label for the link.
1041 * @return a content tree for the package link.
1042 */
1043 public Content getPackageLink(PackageDoc pkg, String label) {
1044 return getPackageLink(pkg, new StringContent(label));
1045 }
1047 /**
1048 * Return the link to the given package.
1049 *
1050 * @param pkg the package to link to.
1051 * @param label the label for the link.
1052 * @return a content tree for the package link.
1053 */
1054 public Content getPackageLink(PackageDoc pkg, Content label) {
1055 boolean included = pkg != null && pkg.isIncluded();
1056 if (! included) {
1057 PackageDoc[] packages = configuration.packages;
1058 for (int i = 0; i < packages.length; i++) {
1059 if (packages[i].equals(pkg)) {
1060 included = true;
1061 break;
1062 }
1063 }
1064 }
1065 if (included || pkg == null) {
1066 return getHyperLink(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
1067 label);
1068 } else {
1069 DocLink crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
1070 if (crossPkgLink != null) {
1071 return getHyperLink(crossPkgLink, label);
1072 } else {
1073 return label;
1074 }
1075 }
1076 }
1078 public Content italicsClassName(ClassDoc cd, boolean qual) {
1079 Content name = new StringContent((qual)? cd.qualifiedName(): cd.name());
1080 return (cd.isInterface())? HtmlTree.I(name): name;
1081 }
1083 /**
1084 * Add the link to the content tree.
1085 *
1086 * @param doc program element doc for which the link will be added
1087 * @param label label for the link
1088 * @param htmltree the content tree to which the link will be added
1089 */
1090 public void addSrcLink(ProgramElementDoc doc, Content label, Content htmltree) {
1091 if (doc == null) {
1092 return;
1093 }
1094 ClassDoc cd = doc.containingClass();
1095 if (cd == null) {
1096 //d must be a class doc since in has no containing class.
1097 cd = (ClassDoc) doc;
1098 }
1099 DocPath href = pathToRoot
1100 .resolve(DocPaths.SOURCE_OUTPUT)
1101 .resolve(DocPath.forClass(cd));
1102 Content linkContent = getHyperLink(href.fragment(SourceToHTMLConverter.getAnchorName(doc)), label, "", "");
1103 htmltree.addContent(linkContent);
1104 }
1106 /**
1107 * Return the link to the given class.
1108 *
1109 * @param linkInfo the information about the link.
1110 *
1111 * @return the link for the given class.
1112 */
1113 public Content getLink(LinkInfoImpl linkInfo) {
1114 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1115 return factory.getLink(linkInfo);
1116 }
1118 /**
1119 * Return the type parameters for the given class.
1120 *
1121 * @param linkInfo the information about the link.
1122 * @return the type for the given class.
1123 */
1124 public Content getTypeParameterLinks(LinkInfoImpl linkInfo) {
1125 LinkFactoryImpl factory = new LinkFactoryImpl(this);
1126 return factory.getTypeParameterLinks(linkInfo, false);
1127 }
1129 /*************************************************************
1130 * Return a class cross link to external class documentation.
1131 * The name must be fully qualified to determine which package
1132 * the class is in. The -link option does not allow users to
1133 * link to external classes in the "default" package.
1134 *
1135 * @param qualifiedClassName the qualified name of the external class.
1136 * @param refMemName the name of the member being referenced. This should
1137 * be null or empty string if no member is being referenced.
1138 * @param label the label for the external link.
1139 * @param strong true if the link should be strong.
1140 * @param style the style of the link.
1141 * @param code true if the label should be code font.
1142 */
1143 public Content getCrossClassLink(String qualifiedClassName, String refMemName,
1144 Content label, boolean strong, String style,
1145 boolean code) {
1146 String className = "";
1147 String packageName = qualifiedClassName == null ? "" : qualifiedClassName;
1148 int periodIndex;
1149 while ((periodIndex = packageName.lastIndexOf('.')) != -1) {
1150 className = packageName.substring(periodIndex + 1, packageName.length()) +
1151 (className.length() > 0 ? "." + className : "");
1152 Content defaultLabel = new StringContent(className);
1153 if (code)
1154 defaultLabel = HtmlTree.CODE(defaultLabel);
1155 packageName = packageName.substring(0, periodIndex);
1156 if (getCrossPackageLink(packageName) != null) {
1157 //The package exists in external documentation, so link to the external
1158 //class (assuming that it exists). This is definitely a limitation of
1159 //the -link option. There are ways to determine if an external package
1160 //exists, but no way to determine if the external class exists. We just
1161 //have to assume that it does.
1162 DocLink link = configuration.extern.getExternalLink(packageName, pathToRoot,
1163 className + ".html", refMemName);
1164 return getHyperLink(link,
1165 (label == null) || label.isEmpty() ? defaultLabel : label,
1166 strong, style,
1167 configuration.getText("doclet.Href_Class_Or_Interface_Title", packageName),
1168 "");
1169 }
1170 }
1171 return null;
1172 }
1174 public boolean isClassLinkable(ClassDoc cd) {
1175 if (cd.isIncluded()) {
1176 return configuration.isGeneratedDoc(cd);
1177 }
1178 return configuration.extern.isExternal(cd);
1179 }
1181 public DocLink getCrossPackageLink(String pkgName) {
1182 return configuration.extern.getExternalLink(pkgName, pathToRoot,
1183 DocPaths.PACKAGE_SUMMARY.getPath());
1184 }
1186 /**
1187 * Get the class link.
1188 *
1189 * @param context the id of the context where the link will be added
1190 * @param cd the class doc to link to
1191 * @return a content tree for the link
1192 */
1193 public Content getQualifiedClassLink(LinkInfoImpl.Kind context, ClassDoc cd) {
1194 return getLink(new LinkInfoImpl(configuration, context, cd)
1195 .label(configuration.getClassName(cd)));
1196 }
1198 /**
1199 * Add the class link.
1200 *
1201 * @param context the id of the context where the link will be added
1202 * @param cd the class doc to link to
1203 * @param contentTree the content tree to which the link will be added
1204 */
1205 public void addPreQualifiedClassLink(LinkInfoImpl.Kind context, ClassDoc cd, Content contentTree) {
1206 addPreQualifiedClassLink(context, cd, false, contentTree);
1207 }
1209 /**
1210 * Retrieve the class link with the package portion of the label in
1211 * plain text. If the qualifier is excluded, it will not be included in the
1212 * link label.
1213 *
1214 * @param cd the class to link to.
1215 * @param isStrong true if the link should be strong.
1216 * @return the link with the package portion of the label in plain text.
1217 */
1218 public Content getPreQualifiedClassLink(LinkInfoImpl.Kind context,
1219 ClassDoc cd, boolean isStrong) {
1220 ContentBuilder classlink = new ContentBuilder();
1221 PackageDoc pd = cd.containingPackage();
1222 if (pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1223 classlink.addContent(getPkgName(cd));
1224 }
1225 classlink.addContent(getLink(new LinkInfoImpl(configuration,
1226 context, cd).label(cd.name()).strong(isStrong)));
1227 return classlink;
1228 }
1230 /**
1231 * Add the class link with the package portion of the label in
1232 * plain text. If the qualifier is excluded, it will not be included in the
1233 * link label.
1234 *
1235 * @param context the id of the context where the link will be added
1236 * @param cd the class to link to
1237 * @param isStrong true if the link should be strong
1238 * @param contentTree the content tree to which the link with be added
1239 */
1240 public void addPreQualifiedClassLink(LinkInfoImpl.Kind context,
1241 ClassDoc cd, boolean isStrong, Content contentTree) {
1242 PackageDoc pd = cd.containingPackage();
1243 if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
1244 contentTree.addContent(getPkgName(cd));
1245 }
1246 contentTree.addContent(getLink(new LinkInfoImpl(configuration,
1247 context, cd).label(cd.name()).strong(isStrong)));
1248 }
1250 /**
1251 * Add the class link, with only class name as the strong link and prefixing
1252 * plain package name.
1253 *
1254 * @param context the id of the context where the link will be added
1255 * @param cd the class to link to
1256 * @param contentTree the content tree to which the link with be added
1257 */
1258 public void addPreQualifiedStrongClassLink(LinkInfoImpl.Kind context, ClassDoc cd, Content contentTree) {
1259 addPreQualifiedClassLink(context, cd, true, contentTree);
1260 }
1262 /**
1263 * Get the link for the given member.
1264 *
1265 * @param context the id of the context where the link will be added
1266 * @param doc the member being linked to
1267 * @param label the label for the link
1268 * @return a content tree for the doc link
1269 */
1270 public Content getDocLink(LinkInfoImpl.Kind context, MemberDoc doc, String label) {
1271 return getDocLink(context, doc.containingClass(), doc,
1272 new StringContent(label));
1273 }
1275 /**
1276 * Return the link for the given member.
1277 *
1278 * @param context the id of the context where the link will be printed.
1279 * @param doc the member being linked to.
1280 * @param label the label for the link.
1281 * @param strong true if the link should be strong.
1282 * @return the link for the given member.
1283 */
1284 public Content getDocLink(LinkInfoImpl.Kind context, MemberDoc doc, String label,
1285 boolean strong) {
1286 return getDocLink(context, doc.containingClass(), doc, label, strong);
1287 }
1289 /**
1290 * Return the link for the given member.
1291 *
1292 * @param context the id of the context where the link will be printed.
1293 * @param classDoc the classDoc that we should link to. This is not
1294 * necessarily equal to doc.containingClass(). We may be
1295 * inheriting comments.
1296 * @param doc the member being linked to.
1297 * @param label the label for the link.
1298 * @param strong true if the link should be strong.
1299 * @return the link for the given member.
1300 */
1301 public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
1302 String label, boolean strong) {
1303 return getDocLink(context, classDoc, doc, label, strong, false);
1304 }
1306 /**
1307 * Return the link for the given member.
1308 *
1309 * @param context the id of the context where the link will be printed.
1310 * @param classDoc the classDoc that we should link to. This is not
1311 * necessarily equal to doc.containingClass(). We may be
1312 * inheriting comments.
1313 * @param doc the member being linked to.
1314 * @param label the label for the link.
1315 * @param strong true if the link should be strong.
1316 * @param isProperty true if the doc parameter is a JavaFX property.
1317 * @return the link for the given member.
1318 */
1319 public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
1320 String label, boolean strong, boolean isProperty) {
1321 return getDocLink(context, classDoc, doc, new RawHtml(label), strong, isProperty);
1322 }
1324 public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
1325 Content label, boolean strong, boolean isProperty) {
1326 if (! (doc.isIncluded() ||
1327 Util.isLinkable(classDoc, configuration))) {
1328 return label;
1329 } else if (doc instanceof ExecutableMemberDoc) {
1330 ExecutableMemberDoc emd = (ExecutableMemberDoc)doc;
1331 return getLink(new LinkInfoImpl(configuration, context, classDoc)
1332 .label(label).where(getAnchor(emd, isProperty)).strong(strong));
1333 } else if (doc instanceof MemberDoc) {
1334 return getLink(new LinkInfoImpl(configuration, context, classDoc)
1335 .label(label).where(doc.name()).strong(strong));
1336 } else {
1337 return label;
1338 }
1339 }
1341 /**
1342 * Return the link for the given member.
1343 *
1344 * @param context the id of the context where the link will be added
1345 * @param classDoc the classDoc that we should link to. This is not
1346 * necessarily equal to doc.containingClass(). We may be
1347 * inheriting comments
1348 * @param doc the member being linked to
1349 * @param label the label for the link
1350 * @return the link for the given member
1351 */
1352 public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
1353 Content label) {
1354 if (! (doc.isIncluded() ||
1355 Util.isLinkable(classDoc, configuration))) {
1356 return label;
1357 } else if (doc instanceof ExecutableMemberDoc) {
1358 ExecutableMemberDoc emd = (ExecutableMemberDoc) doc;
1359 return getLink(new LinkInfoImpl(configuration, context, classDoc)
1360 .label(label).where(getAnchor(emd)));
1361 } else if (doc instanceof MemberDoc) {
1362 return getLink(new LinkInfoImpl(configuration, context, classDoc)
1363 .label(label).where(doc.name()));
1364 } else {
1365 return label;
1366 }
1367 }
1369 public String getAnchor(ExecutableMemberDoc emd) {
1370 return getAnchor(emd, false);
1371 }
1373 public String getAnchor(ExecutableMemberDoc emd, boolean isProperty) {
1374 if (isProperty) {
1375 return emd.name();
1376 }
1377 StringBuilder signature = new StringBuilder(emd.signature());
1378 StringBuilder signatureParsed = new StringBuilder();
1379 int counter = 0;
1380 for (int i = 0; i < signature.length(); i++) {
1381 char c = signature.charAt(i);
1382 if (c == '<') {
1383 counter++;
1384 } else if (c == '>') {
1385 counter--;
1386 } else if (counter == 0) {
1387 signatureParsed.append(c);
1388 }
1389 }
1390 return emd.name() + signatureParsed.toString();
1391 }
1393 public String seeTagToString(SeeTag see) {
1394 String tagName = see.name();
1395 if (! (tagName.startsWith("@link") || tagName.equals("@see"))) {
1396 return "";
1397 }
1399 String seetext = replaceDocRootDir(see.text());
1401 //Check if @see is an href or "string"
1402 if (seetext.startsWith("<") || seetext.startsWith("\"")) {
1403 return seetext;
1404 }
1406 boolean plain = tagName.equalsIgnoreCase("@linkplain");
1407 Content label = plainOrCode(plain, new RawHtml(see.label()));
1409 //The text from the @see tag. We will output this text when a label is not specified.
1410 Content text = plainOrCode(plain, new RawHtml(seetext));
1412 ClassDoc refClass = see.referencedClass();
1413 String refClassName = see.referencedClassName();
1414 MemberDoc refMem = see.referencedMember();
1415 String refMemName = see.referencedMemberName();
1417 if (refClass == null) {
1418 //@see is not referencing an included class
1419 PackageDoc refPackage = see.referencedPackage();
1420 if (refPackage != null && refPackage.isIncluded()) {
1421 //@see is referencing an included package
1422 if (label.isEmpty())
1423 label = plainOrCode(plain, new StringContent(refPackage.name()));
1424 return getPackageLink(refPackage, label).toString();
1425 } else {
1426 //@see is not referencing an included class or package. Check for cross links.
1427 Content classCrossLink;
1428 DocLink packageCrossLink = getCrossPackageLink(refClassName);
1429 if (packageCrossLink != null) {
1430 //Package cross link found
1431 return getHyperLink(packageCrossLink,
1432 (label.isEmpty() ? text : label)).toString();
1433 } else if ((classCrossLink = getCrossClassLink(refClassName,
1434 refMemName, label, false, "", !plain)) != null) {
1435 //Class cross link found (possibly to a member in the class)
1436 return classCrossLink.toString();
1437 } else {
1438 //No cross link found so print warning
1439 configuration.getDocletSpecificMsg().warning(see.position(), "doclet.see.class_or_package_not_found",
1440 tagName, seetext);
1441 return (label.isEmpty() ? text: label).toString();
1442 }
1443 }
1444 } else if (refMemName == null) {
1445 // Must be a class reference since refClass is not null and refMemName is null.
1446 if (label.isEmpty()) {
1447 label = plainOrCode(plain, new StringContent(refClass.name()));
1448 }
1449 return getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.DEFAULT, refClass)
1450 .label(label)).toString();
1451 } else if (refMem == null) {
1452 // Must be a member reference since refClass is not null and refMemName is not null.
1453 // However, refMem is null, so this referenced member does not exist.
1454 return (label.isEmpty() ? text: label).toString();
1455 } else {
1456 // Must be a member reference since refClass is not null and refMemName is not null.
1457 // refMem is not null, so this @see tag must be referencing a valid member.
1458 ClassDoc containing = refMem.containingClass();
1459 if (see.text().trim().startsWith("#") &&
1460 ! (containing.isPublic() ||
1461 Util.isLinkable(containing, configuration))) {
1462 // Since the link is relative and the holder is not even being
1463 // documented, this must be an inherited link. Redirect it.
1464 // The current class either overrides the referenced member or
1465 // inherits it automatically.
1466 if (this instanceof ClassWriterImpl) {
1467 containing = ((ClassWriterImpl) this).getClassDoc();
1468 } else if (!containing.isPublic()){
1469 configuration.getDocletSpecificMsg().warning(
1470 see.position(), "doclet.see.class_or_package_not_accessible",
1471 tagName, containing.qualifiedName());
1472 } else {
1473 configuration.getDocletSpecificMsg().warning(
1474 see.position(), "doclet.see.class_or_package_not_found",
1475 tagName, seetext);
1476 }
1477 }
1478 if (configuration.currentcd != containing) {
1479 refMemName = containing.name() + "." + refMemName;
1480 }
1481 if (refMem instanceof ExecutableMemberDoc) {
1482 if (refMemName.indexOf('(') < 0) {
1483 refMemName += ((ExecutableMemberDoc)refMem).signature();
1484 }
1485 }
1487 text = plainOrCode(plain, new StringContent(refMemName));
1489 return getDocLink(LinkInfoImpl.Kind.SEE_TAG, containing,
1490 refMem, (label.isEmpty() ? text: label).toString(), false).toString();
1491 }
1492 }
1494 private String plainOrCodeText(boolean plain, String text) {
1495 return (plain || text.isEmpty()) ? text : codeText(text);
1496 }
1498 private Content plainOrCode(boolean plain, Content body) {
1499 return (plain || body.isEmpty()) ? body : HtmlTree.CODE(body);
1500 }
1502 /**
1503 * Add the inline comment.
1504 *
1505 * @param doc the doc for which the inline comment will be added
1506 * @param tag the inline tag to be added
1507 * @param htmltree the content tree to which the comment will be added
1508 */
1509 public void addInlineComment(Doc doc, Tag tag, Content htmltree) {
1510 addCommentTags(doc, tag, tag.inlineTags(), false, false, htmltree);
1511 }
1513 /**
1514 * Add the inline deprecated comment.
1515 *
1516 * @param doc the doc for which the inline deprecated comment will be added
1517 * @param tag the inline tag to be added
1518 * @param htmltree the content tree to which the comment will be added
1519 */
1520 public void addInlineDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
1521 addCommentTags(doc, tag.inlineTags(), true, false, htmltree);
1522 }
1524 /**
1525 * Adds the summary content.
1526 *
1527 * @param doc the doc for which the summary will be generated
1528 * @param htmltree the documentation tree to which the summary will be added
1529 */
1530 public void addSummaryComment(Doc doc, Content htmltree) {
1531 addSummaryComment(doc, doc.firstSentenceTags(), htmltree);
1532 }
1534 /**
1535 * Adds the summary content.
1536 *
1537 * @param doc the doc for which the summary will be generated
1538 * @param firstSentenceTags the first sentence tags for the doc
1539 * @param htmltree the documentation tree to which the summary will be added
1540 */
1541 public void addSummaryComment(Doc doc, Tag[] firstSentenceTags, Content htmltree) {
1542 addCommentTags(doc, firstSentenceTags, false, true, htmltree);
1543 }
1545 public void addSummaryDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
1546 addCommentTags(doc, tag.firstSentenceTags(), true, true, htmltree);
1547 }
1549 /**
1550 * Adds the inline comment.
1551 *
1552 * @param doc the doc for which the inline comments will be generated
1553 * @param htmltree the documentation tree to which the inline comments will be added
1554 */
1555 public void addInlineComment(Doc doc, Content htmltree) {
1556 addCommentTags(doc, doc.inlineTags(), false, false, htmltree);
1557 }
1559 /**
1560 * Adds the comment tags.
1561 *
1562 * @param doc the doc for which the comment tags will be generated
1563 * @param tags the first sentence tags for the doc
1564 * @param depr true if it is deprecated
1565 * @param first true if the first sentence tags should be added
1566 * @param htmltree the documentation tree to which the comment tags will be added
1567 */
1568 private void addCommentTags(Doc doc, Tag[] tags, boolean depr,
1569 boolean first, Content htmltree) {
1570 addCommentTags(doc, null, tags, depr, first, htmltree);
1571 }
1573 /**
1574 * Adds the comment tags.
1575 *
1576 * @param doc the doc for which the comment tags will be generated
1577 * @param holderTag the block tag context for the inline tags
1578 * @param tags the first sentence tags for the doc
1579 * @param depr true if it is deprecated
1580 * @param first true if the first sentence tags should be added
1581 * @param htmltree the documentation tree to which the comment tags will be added
1582 */
1583 private void addCommentTags(Doc doc, Tag holderTag, Tag[] tags, boolean depr,
1584 boolean first, Content htmltree) {
1585 if(configuration.nocomment){
1586 return;
1587 }
1588 Content div;
1589 Content result = new RawHtml(commentTagsToString(holderTag, doc, tags, first));
1590 if (depr) {
1591 Content italic = HtmlTree.I(result);
1592 div = HtmlTree.DIV(HtmlStyle.block, italic);
1593 htmltree.addContent(div);
1594 }
1595 else {
1596 div = HtmlTree.DIV(HtmlStyle.block, result);
1597 htmltree.addContent(div);
1598 }
1599 if (tags.length == 0) {
1600 htmltree.addContent(getSpace());
1601 }
1602 }
1604 /**
1605 * Converts inline tags and text to text strings, expanding the
1606 * inline tags along the way. Called wherever text can contain
1607 * an inline tag, such as in comments or in free-form text arguments
1608 * to non-inline tags.
1609 *
1610 * @param holderTag specific tag where comment resides
1611 * @param doc specific doc where comment resides
1612 * @param tags array of text tags and inline tags (often alternating)
1613 * present in the text of interest for this doc
1614 * @param isFirstSentence true if text is first sentence
1615 */
1616 public String commentTagsToString(Tag holderTag, Doc doc, Tag[] tags,
1617 boolean isFirstSentence) {
1618 StringBuilder result = new StringBuilder();
1619 boolean textTagChange = false;
1620 // Array of all possible inline tags for this javadoc run
1621 configuration.tagletManager.checkTags(doc, tags, true);
1622 for (int i = 0; i < tags.length; i++) {
1623 Tag tagelem = tags[i];
1624 String tagName = tagelem.name();
1625 if (tagelem instanceof SeeTag) {
1626 result.append(seeTagToString((SeeTag)tagelem));
1627 } else if (! tagName.equals("Text")) {
1628 int originalLength = result.length();
1629 TagletOutput output = TagletWriter.getInlineTagOuput(
1630 configuration.tagletManager, holderTag,
1631 tagelem, getTagletWriterInstance(isFirstSentence));
1632 result.append(output == null ? "" : output.toString());
1633 if (originalLength == 0 && isFirstSentence && tagelem.name().equals("@inheritDoc") && result.length() > 0) {
1634 break;
1635 } else if (configuration.docrootparent.length() > 0 &&
1636 tagelem.name().equals("@docRoot") &&
1637 ((tags[i + 1]).text()).startsWith("/..")) {
1638 //If Xdocrootparent switch ON, set the flag to remove the /.. occurance after
1639 //{@docRoot} tag in the very next Text tag.
1640 textTagChange = true;
1641 continue;
1642 } else {
1643 continue;
1644 }
1645 } else {
1646 String text = tagelem.text();
1647 //If Xdocrootparent switch ON, remove the /.. occurance after {@docRoot} tag.
1648 if (textTagChange) {
1649 text = text.replaceFirst("/..", "");
1650 textTagChange = false;
1651 }
1652 //This is just a regular text tag. The text may contain html links (<a>)
1653 //or inline tag {@docRoot}, which will be handled as special cases.
1654 text = redirectRelativeLinks(tagelem.holder(), text);
1656 // Replace @docRoot only if not represented by an instance of DocRootTaglet,
1657 // that is, only if it was not present in a source file doc comment.
1658 // This happens when inserted by the doclet (a few lines
1659 // above in this method). [It might also happen when passed in on the command
1660 // line as a text argument to an option (like -header).]
1661 text = replaceDocRootDir(text);
1662 if (isFirstSentence) {
1663 text = removeNonInlineHtmlTags(text);
1664 }
1665 StringTokenizer lines = new StringTokenizer(text, "\r\n", true);
1666 StringBuilder textBuff = new StringBuilder();
1667 while (lines.hasMoreTokens()) {
1668 StringBuilder line = new StringBuilder(lines.nextToken());
1669 Util.replaceTabs(configuration, line);
1670 textBuff.append(line.toString());
1671 }
1672 result.append(textBuff);
1673 }
1674 }
1675 return result.toString();
1676 }
1678 /**
1679 * Return true if relative links should not be redirected.
1680 *
1681 * @return Return true if a relative link should not be redirected.
1682 */
1683 private boolean shouldNotRedirectRelativeLinks() {
1684 return this instanceof AnnotationTypeWriter ||
1685 this instanceof ClassWriter ||
1686 this instanceof PackageSummaryWriter;
1687 }
1689 /**
1690 * Suppose a piece of documentation has a relative link. When you copy
1691 * that documentation to another place such as the index or class-use page,
1692 * that relative link will no longer work. We should redirect those links
1693 * so that they will work again.
1694 * <p>
1695 * Here is the algorithm used to fix the link:
1696 * <p>
1697 * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
1698 * <p>
1699 * For example, suppose com.sun.javadoc.RootDoc has this link:
1700 * {@literal <a href="package-summary.html">The package Page</a> }
1701 * <p>
1702 * If this link appeared in the index, we would redirect
1703 * the link like this:
1704 *
1705 * {@literal <a href="./com/sun/javadoc/package-summary.html">The package Page</a>}
1706 *
1707 * @param doc the Doc object whose documentation is being written.
1708 * @param text the text being written.
1709 *
1710 * @return the text, with all the relative links redirected to work.
1711 */
1712 private String redirectRelativeLinks(Doc doc, String text) {
1713 if (doc == null || shouldNotRedirectRelativeLinks()) {
1714 return text;
1715 }
1717 DocPath redirectPathFromRoot;
1718 if (doc instanceof ClassDoc) {
1719 redirectPathFromRoot = DocPath.forPackage(((ClassDoc) doc).containingPackage());
1720 } else if (doc instanceof MemberDoc) {
1721 redirectPathFromRoot = DocPath.forPackage(((MemberDoc) doc).containingPackage());
1722 } else if (doc instanceof PackageDoc) {
1723 redirectPathFromRoot = DocPath.forPackage((PackageDoc) doc);
1724 } else {
1725 return text;
1726 }
1728 //Redirect all relative links.
1729 int end, begin = text.toLowerCase().indexOf("<a");
1730 if(begin >= 0){
1731 StringBuilder textBuff = new StringBuilder(text);
1733 while(begin >=0){
1734 if (textBuff.length() > begin + 2 && ! Character.isWhitespace(textBuff.charAt(begin+2))) {
1735 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
1736 continue;
1737 }
1739 begin = textBuff.indexOf("=", begin) + 1;
1740 end = textBuff.indexOf(">", begin +1);
1741 if(begin == 0){
1742 //Link has no equal symbol.
1743 configuration.root.printWarning(
1744 doc.position(),
1745 configuration.getText("doclet.malformed_html_link_tag", text));
1746 break;
1747 }
1748 if (end == -1) {
1749 //Break without warning. This <a> tag is not necessarily malformed. The text
1750 //might be missing '>' character because the href has an inline tag.
1751 break;
1752 }
1753 if (textBuff.substring(begin, end).indexOf("\"") != -1){
1754 begin = textBuff.indexOf("\"", begin) + 1;
1755 end = textBuff.indexOf("\"", begin +1);
1756 if (begin == 0 || end == -1){
1757 //Link is missing a quote.
1758 break;
1759 }
1760 }
1761 String relativeLink = textBuff.substring(begin, end);
1762 if (!(relativeLink.toLowerCase().startsWith("mailto:") ||
1763 relativeLink.toLowerCase().startsWith("http:") ||
1764 relativeLink.toLowerCase().startsWith("https:") ||
1765 relativeLink.toLowerCase().startsWith("file:"))) {
1766 relativeLink = "{@"+(new DocRootTaglet()).getName() + "}/"
1767 + redirectPathFromRoot.resolve(relativeLink).getPath();
1768 textBuff.replace(begin, end, relativeLink);
1769 }
1770 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
1771 }
1772 return textBuff.toString();
1773 }
1774 return text;
1775 }
1777 public String removeNonInlineHtmlTags(String text) {
1778 if (text.indexOf('<') < 0) {
1779 return text;
1780 }
1781 String noninlinetags[] = { "<ul>", "</ul>", "<ol>", "</ol>",
1782 "<dl>", "</dl>", "<table>", "</table>",
1783 "<tr>", "</tr>", "<td>", "</td>",
1784 "<th>", "</th>", "<p>", "</p>",
1785 "<li>", "</li>", "<dd>", "</dd>",
1786 "<dir>", "</dir>", "<dt>", "</dt>",
1787 "<h1>", "</h1>", "<h2>", "</h2>",
1788 "<h3>", "</h3>", "<h4>", "</h4>",
1789 "<h5>", "</h5>", "<h6>", "</h6>",
1790 "<pre>", "</pre>", "<menu>", "</menu>",
1791 "<listing>", "</listing>", "<hr>",
1792 "<blockquote>", "</blockquote>",
1793 "<center>", "</center>",
1794 "<UL>", "</UL>", "<OL>", "</OL>",
1795 "<DL>", "</DL>", "<TABLE>", "</TABLE>",
1796 "<TR>", "</TR>", "<TD>", "</TD>",
1797 "<TH>", "</TH>", "<P>", "</P>",
1798 "<LI>", "</LI>", "<DD>", "</DD>",
1799 "<DIR>", "</DIR>", "<DT>", "</DT>",
1800 "<H1>", "</H1>", "<H2>", "</H2>",
1801 "<H3>", "</H3>", "<H4>", "</H4>",
1802 "<H5>", "</H5>", "<H6>", "</H6>",
1803 "<PRE>", "</PRE>", "<MENU>", "</MENU>",
1804 "<LISTING>", "</LISTING>", "<HR>",
1805 "<BLOCKQUOTE>", "</BLOCKQUOTE>",
1806 "<CENTER>", "</CENTER>"
1807 };
1808 for (int i = 0; i < noninlinetags.length; i++) {
1809 text = replace(text, noninlinetags[i], "");
1810 }
1811 return text;
1812 }
1814 public String replace(String text, String tobe, String by) {
1815 while (true) {
1816 int startindex = text.indexOf(tobe);
1817 if (startindex < 0) {
1818 return text;
1819 }
1820 int endindex = startindex + tobe.length();
1821 StringBuilder replaced = new StringBuilder();
1822 if (startindex > 0) {
1823 replaced.append(text.substring(0, startindex));
1824 }
1825 replaced.append(by);
1826 if (text.length() > endindex) {
1827 replaced.append(text.substring(endindex));
1828 }
1829 text = replaced.toString();
1830 }
1831 }
1833 /**
1834 * Returns a link to the stylesheet file.
1835 *
1836 * @return an HtmlTree for the lINK tag which provides the stylesheet location
1837 */
1838 public HtmlTree getStyleSheetProperties() {
1839 String stylesheetfile = configuration.stylesheetfile;
1840 DocPath stylesheet;
1841 if (stylesheetfile.isEmpty()) {
1842 stylesheet = DocPaths.STYLESHEET;
1843 } else {
1844 DocFile file = DocFile.createFileForInput(configuration, stylesheetfile);
1845 stylesheet = DocPath.create(file.getName());
1846 }
1847 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css",
1848 pathToRoot.resolve(stylesheet).getPath(),
1849 "Style");
1850 return link;
1851 }
1853 /**
1854 * Returns a link to the JavaScript file.
1855 *
1856 * @return an HtmlTree for the Script tag which provides the JavaScript location
1857 */
1858 public HtmlTree getScriptProperties() {
1859 HtmlTree script = HtmlTree.SCRIPT("text/javascript",
1860 pathToRoot.resolve(DocPaths.JAVASCRIPT).getPath());
1861 return script;
1862 }
1864 /**
1865 * According to
1866 * <cite>The Java™ Language Specification</cite>,
1867 * all the outer classes and static nested classes are core classes.
1868 */
1869 public boolean isCoreClass(ClassDoc cd) {
1870 return cd.containingClass() == null || cd.isStatic();
1871 }
1873 /**
1874 * Adds the annotatation types for the given packageDoc.
1875 *
1876 * @param packageDoc the package to write annotations for.
1877 * @param htmltree the documentation tree to which the annotation info will be
1878 * added
1879 */
1880 public void addAnnotationInfo(PackageDoc packageDoc, Content htmltree) {
1881 addAnnotationInfo(packageDoc, packageDoc.annotations(), htmltree);
1882 }
1884 /**
1885 * Add the annotation types of the executable receiver.
1886 *
1887 * @param method the executable to write the receiver annotations for.
1888 * @param descList list of annotation description.
1889 * @param htmltree the documentation tree to which the annotation info will be
1890 * added
1891 */
1892 public void addReceiverAnnotationInfo(ExecutableMemberDoc method, AnnotationDesc[] descList,
1893 Content htmltree) {
1894 addAnnotationInfo(0, method, descList, false, htmltree);
1895 }
1897 /**
1898 * Adds the annotatation types for the given doc.
1899 *
1900 * @param doc the package to write annotations for
1901 * @param htmltree the content tree to which the annotation types will be added
1902 */
1903 public void addAnnotationInfo(ProgramElementDoc doc, Content htmltree) {
1904 addAnnotationInfo(doc, doc.annotations(), htmltree);
1905 }
1907 /**
1908 * Add the annotatation types for the given doc and parameter.
1909 *
1910 * @param indent the number of spaces to indent the parameters.
1911 * @param doc the doc to write annotations for.
1912 * @param param the parameter to write annotations for.
1913 * @param tree the content tree to which the annotation types will be added
1914 */
1915 public boolean addAnnotationInfo(int indent, Doc doc, Parameter param,
1916 Content tree) {
1917 return addAnnotationInfo(indent, doc, param.annotations(), false, tree);
1918 }
1920 /**
1921 * Adds the annotatation types for the given doc.
1922 *
1923 * @param doc the doc to write annotations for.
1924 * @param descList the array of {@link AnnotationDesc}.
1925 * @param htmltree the documentation tree to which the annotation info will be
1926 * added
1927 */
1928 private void addAnnotationInfo(Doc doc, AnnotationDesc[] descList,
1929 Content htmltree) {
1930 addAnnotationInfo(0, doc, descList, true, htmltree);
1931 }
1933 /**
1934 * Adds the annotatation types for the given doc.
1935 *
1936 * @param indent the number of extra spaces to indent the annotations.
1937 * @param doc the doc to write annotations for.
1938 * @param descList the array of {@link AnnotationDesc}.
1939 * @param htmltree the documentation tree to which the annotation info will be
1940 * added
1941 */
1942 private boolean addAnnotationInfo(int indent, Doc doc,
1943 AnnotationDesc[] descList, boolean lineBreak, Content htmltree) {
1944 List<String> annotations = getAnnotations(indent, descList, lineBreak);
1945 String sep ="";
1946 if (annotations.size() == 0) {
1947 return false;
1948 }
1949 Content annotationContent;
1950 for (Iterator<String> iter = annotations.iterator(); iter.hasNext();) {
1951 htmltree.addContent(sep);
1952 annotationContent = new RawHtml(iter.next());
1953 htmltree.addContent(annotationContent);
1954 sep = " ";
1955 }
1956 return true;
1957 }
1959 /**
1960 * Return the string representations of the annotation types for
1961 * the given doc.
1962 *
1963 * @param indent the number of extra spaces to indent the annotations.
1964 * @param descList the array of {@link AnnotationDesc}.
1965 * @param linkBreak if true, add new line between each member value.
1966 * @return an array of strings representing the annotations being
1967 * documented.
1968 */
1969 private List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak) {
1970 return getAnnotations(indent, descList, linkBreak, true);
1971 }
1973 /**
1974 * Return the string representations of the annotation types for
1975 * the given doc.
1976 *
1977 * A {@code null} {@code elementType} indicates that all the
1978 * annotations should be returned without any filtering.
1979 *
1980 * @param indent the number of extra spaces to indent the annotations.
1981 * @param descList the array of {@link AnnotationDesc}.
1982 * @param linkBreak if true, add new line between each member value.
1983 * @param elementType the type of targeted element (used for filtering
1984 * type annotations from declaration annotations)
1985 * @return an array of strings representing the annotations being
1986 * documented.
1987 */
1988 public List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak,
1989 boolean isJava5DeclarationLocation) {
1990 List<String> results = new ArrayList<String>();
1991 StringBuilder annotation;
1992 for (int i = 0; i < descList.length; i++) {
1993 AnnotationTypeDoc annotationDoc = descList[i].annotationType();
1994 // If an annotation is not documented, do not add it to the list. If
1995 // the annotation is of a repeatable type, and if it is not documented
1996 // and also if its container annotation is not documented, do not add it
1997 // to the list. If an annotation of a repeatable type is not documented
1998 // but its container is documented, it will be added to the list.
1999 if (! Util.isDocumentedAnnotation(annotationDoc) &&
2000 (!isAnnotationDocumented && !isContainerDocumented)) {
2001 continue;
2002 }
2003 /* TODO: check logic here to correctly handle declaration
2004 * and type annotations.
2005 if (Util.isDeclarationAnnotation(annotationDoc, isJava5DeclarationLocation)) {
2006 continue;
2007 }*/
2008 annotation = new StringBuilder();
2009 isAnnotationDocumented = false;
2010 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
2011 LinkInfoImpl.Kind.ANNOTATION, annotationDoc);
2012 AnnotationDesc.ElementValuePair[] pairs = descList[i].elementValues();
2013 // If the annotation is synthesized, do not print the container.
2014 if (descList[i].isSynthesized()) {
2015 for (int j = 0; j < pairs.length; j++) {
2016 AnnotationValue annotationValue = pairs[j].value();
2017 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
2018 if (annotationValue.value() instanceof AnnotationValue[]) {
2019 AnnotationValue[] annotationArray =
2020 (AnnotationValue[]) annotationValue.value();
2021 annotationTypeValues.addAll(Arrays.asList(annotationArray));
2022 } else {
2023 annotationTypeValues.add(annotationValue);
2024 }
2025 String sep = "";
2026 for (AnnotationValue av : annotationTypeValues) {
2027 annotation.append(sep);
2028 annotation.append(annotationValueToString(av));
2029 sep = " ";
2030 }
2031 }
2032 }
2033 else if (isAnnotationArray(pairs)) {
2034 // If the container has 1 or more value defined and if the
2035 // repeatable type annotation is not documented, do not print
2036 // the container.
2037 if (pairs.length == 1 && isAnnotationDocumented) {
2038 AnnotationValue[] annotationArray =
2039 (AnnotationValue[]) (pairs[0].value()).value();
2040 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
2041 annotationTypeValues.addAll(Arrays.asList(annotationArray));
2042 String sep = "";
2043 for (AnnotationValue av : annotationTypeValues) {
2044 annotation.append(sep);
2045 annotation.append(annotationValueToString(av));
2046 sep = " ";
2047 }
2048 }
2049 // If the container has 1 or more value defined and if the
2050 // repeatable type annotation is not documented, print the container.
2051 else {
2052 addAnnotations(annotationDoc, linkInfo, annotation, pairs,
2053 indent, false);
2054 }
2055 }
2056 else {
2057 addAnnotations(annotationDoc, linkInfo, annotation, pairs,
2058 indent, linkBreak);
2059 }
2060 annotation.append(linkBreak ? DocletConstants.NL : "");
2061 results.add(annotation.toString());
2062 }
2063 return results;
2064 }
2066 /**
2067 * Add annotation to the annotation string.
2068 *
2069 * @param annotationDoc the annotation being documented
2070 * @param linkInfo the information about the link
2071 * @param annotation the annotation string to which the annotation will be added
2072 * @param pairs annotation type element and value pairs
2073 * @param indent the number of extra spaces to indent the annotations.
2074 * @param linkBreak if true, add new line between each member value
2075 */
2076 private void addAnnotations(AnnotationTypeDoc annotationDoc, LinkInfoImpl linkInfo,
2077 StringBuilder annotation, AnnotationDesc.ElementValuePair[] pairs,
2078 int indent, boolean linkBreak) {
2079 linkInfo.label = new StringContent("@" + annotationDoc.name());
2080 annotation.append(getLink(linkInfo));
2081 if (pairs.length > 0) {
2082 annotation.append('(');
2083 for (int j = 0; j < pairs.length; j++) {
2084 if (j > 0) {
2085 annotation.append(",");
2086 if (linkBreak) {
2087 annotation.append(DocletConstants.NL);
2088 int spaces = annotationDoc.name().length() + 2;
2089 for (int k = 0; k < (spaces + indent); k++) {
2090 annotation.append(' ');
2091 }
2092 }
2093 }
2094 annotation.append(getDocLink(LinkInfoImpl.Kind.ANNOTATION,
2095 pairs[j].element(), pairs[j].element().name(), false));
2096 annotation.append('=');
2097 AnnotationValue annotationValue = pairs[j].value();
2098 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
2099 if (annotationValue.value() instanceof AnnotationValue[]) {
2100 AnnotationValue[] annotationArray =
2101 (AnnotationValue[]) annotationValue.value();
2102 annotationTypeValues.addAll(Arrays.asList(annotationArray));
2103 } else {
2104 annotationTypeValues.add(annotationValue);
2105 }
2106 annotation.append(annotationTypeValues.size() == 1 ? "" : "{");
2107 String sep = "";
2108 for (AnnotationValue av : annotationTypeValues) {
2109 annotation.append(sep);
2110 annotation.append(annotationValueToString(av));
2111 sep = ",";
2112 }
2113 annotation.append(annotationTypeValues.size() == 1 ? "" : "}");
2114 isContainerDocumented = false;
2115 }
2116 annotation.append(")");
2117 }
2118 }
2120 /**
2121 * Check if the annotation contains an array of annotation as a value. This
2122 * check is to verify if a repeatable type annotation is present or not.
2123 *
2124 * @param pairs annotation type element and value pairs
2125 *
2126 * @return true if the annotation contains an array of annotation as a value.
2127 */
2128 private boolean isAnnotationArray(AnnotationDesc.ElementValuePair[] pairs) {
2129 AnnotationValue annotationValue;
2130 for (int j = 0; j < pairs.length; j++) {
2131 annotationValue = pairs[j].value();
2132 if (annotationValue.value() instanceof AnnotationValue[]) {
2133 AnnotationValue[] annotationArray =
2134 (AnnotationValue[]) annotationValue.value();
2135 if (annotationArray.length > 1) {
2136 if (annotationArray[0].value() instanceof AnnotationDesc) {
2137 AnnotationTypeDoc annotationDoc =
2138 ((AnnotationDesc) annotationArray[0].value()).annotationType();
2139 isContainerDocumented = true;
2140 if (Util.isDocumentedAnnotation(annotationDoc)) {
2141 isAnnotationDocumented = true;
2142 }
2143 return true;
2144 }
2145 }
2146 }
2147 }
2148 return false;
2149 }
2151 private String annotationValueToString(AnnotationValue annotationValue) {
2152 if (annotationValue.value() instanceof Type) {
2153 Type type = (Type) annotationValue.value();
2154 if (type.asClassDoc() != null) {
2155 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
2156 LinkInfoImpl.Kind.ANNOTATION, type);
2157 linkInfo.label = new StringContent((type.asClassDoc().isIncluded() ?
2158 type.typeName() :
2159 type.qualifiedTypeName()) + type.dimension() + ".class");
2160 return getLink(linkInfo).toString();
2161 } else {
2162 return type.typeName() + type.dimension() + ".class";
2163 }
2164 } else if (annotationValue.value() instanceof AnnotationDesc) {
2165 List<String> list = getAnnotations(0,
2166 new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
2167 false);
2168 StringBuilder buf = new StringBuilder();
2169 for (String s: list) {
2170 buf.append(s);
2171 }
2172 return buf.toString();
2173 } else if (annotationValue.value() instanceof MemberDoc) {
2174 return getDocLink(LinkInfoImpl.Kind.ANNOTATION,
2175 (MemberDoc) annotationValue.value(),
2176 ((MemberDoc) annotationValue.value()).name(), false).toString();
2177 } else {
2178 return annotationValue.toString();
2179 }
2180 }
2182 /**
2183 * Return the configuation for this doclet.
2184 *
2185 * @return the configuration for this doclet.
2186 */
2187 public Configuration configuration() {
2188 return configuration;
2189 }
2190 }