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