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