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