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