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