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