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