src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java

Tue, 14 May 2013 10:14:53 -0700

author
jjg
date
Tue, 14 May 2013 10:14:53 -0700
changeset 1740
ce4f0769b4b2
parent 1738
6ea964c78845
child 1741
4c43e51433ba
permissions
-rw-r--r--

8011668: Allow HTMLWriter.getResource to take Content args
Reviewed-by: darcy

     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 display length used for indentation while generating the class page.
    79      */
    80     public int displayLength = 0;
    82     /**
    83      * The global configuration information for this run.
    84      */
    85     public final ConfigurationImpl configuration;
    87     /**
    88      * To check whether annotation heading is printed or not.
    89      */
    90     protected boolean printedAnnotationHeading = 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 {&#064;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 {&#064;docRoot} where one was
   120      * missing.  (Also see DocRootTaglet for {&#064;docRoot} tags in doc
   121      * comments.)
   122      * <p>
   123      * Replace {&#064;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 {&#064;docRoot}, when
   128      * the HTML page for source file p/C1.java is being generated, the
   129      * {&#064;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 '&amp;#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         TagletOutputImpl output = new TagletOutputImpl("");
   255         TagletWriter.genTagOuput(configuration.tagletManager, doc,
   256             configuration.tagletManager.getCustomTags(doc),
   257                 getTagletWriterInstance(false), output);
   258         String outputString = output.toString().trim();
   259         if (!outputString.isEmpty()) {
   260             Content resultString = new RawHtml(outputString);
   261             dl.addContent(resultString);
   262         }
   263         htmltree.addContent(dl);
   264     }
   266     /**
   267      * Check whether there are any tags for Serialization Overview
   268      * section to be printed.
   269      *
   270      * @param field the FieldDoc object to check for tags.
   271      * @return true if there are tags to be printed else return false.
   272      */
   273     protected boolean hasSerializationOverviewTags(FieldDoc field) {
   274         TagletOutputImpl output = new TagletOutputImpl("");
   275         TagletWriter.genTagOuput(configuration.tagletManager, field,
   276             configuration.tagletManager.getCustomTags(field),
   277                 getTagletWriterInstance(false), output);
   278         return (!output.toString().trim().isEmpty());
   279     }
   281     /**
   282      * Returns a TagletWriter that knows how to write HTML.
   283      *
   284      * @return a TagletWriter that knows how to write HTML.
   285      */
   286     public TagletWriter getTagletWriterInstance(boolean isFirstSentence) {
   287         return new TagletWriterImpl(this, isFirstSentence);
   288     }
   290     /**
   291      * Get Package link, with target frame.
   292      *
   293      * @param pd The link will be to the "package-summary.html" page for this package
   294      * @param target name of the target frame
   295      * @param label tag for the link
   296      * @return a content for the target package link
   297      */
   298     public Content getTargetPackageLink(PackageDoc pd, String target,
   299             Content label) {
   300         return getHyperLink(pathString(pd, DocPaths.PACKAGE_SUMMARY), label, "", target);
   301     }
   303     /**
   304      * Get Profile Package link, with target frame.
   305      *
   306      * @param pd the packageDoc object
   307      * @param target name of the target frame
   308      * @param label tag for the link
   309      * @param profileName the name of the profile being documented
   310      * @return a content for the target profile packages link
   311      */
   312     public Content getTargetProfilePackageLink(PackageDoc pd, String target,
   313             Content label, String profileName) {
   314         return getHyperLink(pathString(pd, DocPaths.profilePackageSummary(profileName)),
   315                 label, "", target);
   316     }
   318     /**
   319      * Get Profile link, with target frame.
   320      *
   321      * @param target name of the target frame
   322      * @param label tag for the link
   323      * @param profileName the name of the profile being documented
   324      * @return a content for the target profile link
   325      */
   326     public Content getTargetProfileLink(String target, Content label,
   327             String profileName) {
   328         return getHyperLink(pathToRoot.resolve(
   329                 DocPaths.profileSummary(profileName)), label, "", target);
   330     }
   332     /**
   333      * Get the type name for profile search.
   334      *
   335      * @param cd the classDoc object for which the type name conversion is needed
   336      * @return a type name string for the type
   337      */
   338     public String getTypeNameForProfile(ClassDoc cd) {
   339         StringBuilder typeName =
   340                 new StringBuilder((cd.containingPackage()).name().replace(".", "/"));
   341         typeName.append("/")
   342                 .append(cd.name().replace(".", "$"));
   343         return typeName.toString();
   344     }
   346     /**
   347      * Check if a type belongs to a profile.
   348      *
   349      * @param cd the classDoc object that needs to be checked
   350      * @param profileValue the profile in which the type needs to be checked
   351      * @return true if the type is in the profile
   352      */
   353     public boolean isTypeInProfile(ClassDoc cd, int profileValue) {
   354         return (configuration.profiles.getProfile(getTypeNameForProfile(cd)) <= profileValue);
   355     }
   357     public void addClassesSummary(ClassDoc[] classes, String label,
   358             String tableSummary, String[] tableHeader, Content summaryContentTree,
   359             int profileValue) {
   360         if(classes.length > 0) {
   361             Arrays.sort(classes);
   362             Content caption = getTableCaption(label);
   363             Content table = HtmlTree.TABLE(HtmlStyle.packageSummary, 0, 3, 0,
   364                     tableSummary, caption);
   365             table.addContent(getSummaryTableHeader(tableHeader, "col"));
   366             Content tbody = new HtmlTree(HtmlTag.TBODY);
   367             for (int i = 0; i < classes.length; i++) {
   368                 if (!isTypeInProfile(classes[i], profileValue)) {
   369                     continue;
   370                 }
   371                 if (!Util.isCoreClass(classes[i]) ||
   372                     !configuration.isGeneratedDoc(classes[i])) {
   373                     continue;
   374                 }
   375                 Content classContent = getLink(new LinkInfoImpl(
   376                         configuration, LinkInfoImpl.Kind.PACKAGE, classes[i]));
   377                 Content tdClass = HtmlTree.TD(HtmlStyle.colFirst, classContent);
   378                 HtmlTree tr = HtmlTree.TR(tdClass);
   379                 if (i%2 == 0)
   380                     tr.addStyle(HtmlStyle.altColor);
   381                 else
   382                     tr.addStyle(HtmlStyle.rowColor);
   383                 HtmlTree tdClassDescription = new HtmlTree(HtmlTag.TD);
   384                 tdClassDescription.addStyle(HtmlStyle.colLast);
   385                 if (Util.isDeprecated(classes[i])) {
   386                     tdClassDescription.addContent(deprecatedLabel);
   387                     if (classes[i].tags("deprecated").length > 0) {
   388                         addSummaryDeprecatedComment(classes[i],
   389                             classes[i].tags("deprecated")[0], tdClassDescription);
   390                     }
   391                 }
   392                 else
   393                     addSummaryComment(classes[i], tdClassDescription);
   394                 tr.addContent(tdClassDescription);
   395                 tbody.addContent(tr);
   396             }
   397             table.addContent(tbody);
   398             Content li = HtmlTree.LI(HtmlStyle.blockList, table);
   399             summaryContentTree.addContent(li);
   400         }
   401     }
   403     /**
   404      * Generates the HTML document tree and prints it out.
   405      *
   406      * @param metakeywords Array of String keywords for META tag. Each element
   407      *                     of the array is assigned to a separate META tag.
   408      *                     Pass in null for no array
   409      * @param includeScript true if printing windowtitle script
   410      *                      false for files that appear in the left-hand frames
   411      * @param body the body htmltree to be included in the document
   412      */
   413     public void printHtmlDocument(String[] metakeywords, boolean includeScript,
   414             Content body) throws IOException {
   415         Content htmlDocType = DocType.TRANSITIONAL;
   416         Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
   417         Content head = new HtmlTree(HtmlTag.HEAD);
   418         if (!configuration.notimestamp) {
   419             Content headComment = new Comment(getGeneratedByString());
   420             head.addContent(headComment);
   421         }
   422         if (configuration.charset.length() > 0) {
   423             Content meta = HtmlTree.META("Content-Type", "text/html",
   424                     configuration.charset);
   425             head.addContent(meta);
   426         }
   427         head.addContent(getTitle());
   428         if (!configuration.notimestamp) {
   429             SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
   430             Content meta = HtmlTree.META("date", dateFormat.format(new Date()));
   431             head.addContent(meta);
   432         }
   433         if (metakeywords != null) {
   434             for (int i=0; i < metakeywords.length; i++) {
   435                 Content meta = HtmlTree.META("keywords", metakeywords[i]);
   436                 head.addContent(meta);
   437             }
   438         }
   439         head.addContent(getStyleSheetProperties());
   440         head.addContent(getScriptProperties());
   441         Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
   442                 head, body);
   443         Content htmlDocument = new HtmlDocument(htmlDocType,
   444                 htmlComment, htmlTree);
   445         write(htmlDocument);
   446     }
   448     /**
   449      * Get the window title.
   450      *
   451      * @param title the title string to construct the complete window title
   452      * @return the window title string
   453      */
   454     public String getWindowTitle(String title) {
   455         if (configuration.windowtitle.length() > 0) {
   456             title += " (" + configuration.windowtitle  + ")";
   457         }
   458         return title;
   459     }
   461     /**
   462      * Get user specified header and the footer.
   463      *
   464      * @param header if true print the user provided header else print the
   465      * user provided footer.
   466      */
   467     public Content getUserHeaderFooter(boolean header) {
   468         String content;
   469         if (header) {
   470             content = replaceDocRootDir(configuration.header);
   471         } else {
   472             if (configuration.footer.length() != 0) {
   473                 content = replaceDocRootDir(configuration.footer);
   474             } else {
   475                 content = replaceDocRootDir(configuration.header);
   476             }
   477         }
   478         Content rawContent = new RawHtml(content);
   479         Content em = HtmlTree.EM(rawContent);
   480         return em;
   481     }
   483     /**
   484      * Adds the user specified top.
   485      *
   486      * @param body the content tree to which user specified top will be added
   487      */
   488     public void addTop(Content body) {
   489         Content top = new RawHtml(replaceDocRootDir(configuration.top));
   490         body.addContent(top);
   491     }
   493     /**
   494      * Adds the user specified bottom.
   495      *
   496      * @param body the content tree to which user specified bottom will be added
   497      */
   498     public void addBottom(Content body) {
   499         Content bottom = new RawHtml(replaceDocRootDir(configuration.bottom));
   500         Content small = HtmlTree.SMALL(bottom);
   501         Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
   502         body.addContent(p);
   503     }
   505     /**
   506      * Adds the navigation bar for the Html page at the top and and the bottom.
   507      *
   508      * @param header If true print navigation bar at the top of the page else
   509      * @param body the HtmlTree to which the nav links will be added
   510      */
   511     protected void addNavLinks(boolean header, Content body) {
   512         if (!configuration.nonavbar) {
   513             String allClassesId = "allclasses_";
   514             HtmlTree navDiv = new HtmlTree(HtmlTag.DIV);
   515             if (header) {
   516                 body.addContent(HtmlConstants.START_OF_TOP_NAVBAR);
   517                 navDiv.addStyle(HtmlStyle.topNav);
   518                 allClassesId += "navbar_top";
   519                 Content a = getMarkerAnchor("navbar_top");
   520                 navDiv.addContent(a);
   521                 Content skipLinkContent = getHyperLink(DocLink.fragment("skip-navbar_top"),
   522                         HtmlTree.EMPTY,
   523                         configuration.getText("doclet.Skip_navigation_links"),
   524                         "");
   525                 navDiv.addContent(skipLinkContent);
   526             } else {
   527                 body.addContent(HtmlConstants.START_OF_BOTTOM_NAVBAR);
   528                 navDiv.addStyle(HtmlStyle.bottomNav);
   529                 allClassesId += "navbar_bottom";
   530                 Content a = getMarkerAnchor("navbar_bottom");
   531                 navDiv.addContent(a);
   532                 Content skipLinkContent = getHyperLink(DocLink.fragment("skip-navbar_bottom"),
   533                         HtmlTree.EMPTY,
   534                         configuration.getText("doclet.Skip_navigation_links"),
   535                         "");
   536                 navDiv.addContent(skipLinkContent);
   537             }
   538             if (header) {
   539                 navDiv.addContent(getMarkerAnchor("navbar_top_firstrow"));
   540             } else {
   541                 navDiv.addContent(getMarkerAnchor("navbar_bottom_firstrow"));
   542             }
   543             HtmlTree navList = new HtmlTree(HtmlTag.UL);
   544             navList.addStyle(HtmlStyle.navList);
   545             navList.addAttr(HtmlAttr.TITLE,
   546                             configuration.getText("doclet.Navigation"));
   547             if (configuration.createoverview) {
   548                 navList.addContent(getNavLinkContents());
   549             }
   550             if (configuration.packages.length == 1) {
   551                 navList.addContent(getNavLinkPackage(configuration.packages[0]));
   552             } else if (configuration.packages.length > 1) {
   553                 navList.addContent(getNavLinkPackage());
   554             }
   555             navList.addContent(getNavLinkClass());
   556             if(configuration.classuse) {
   557                 navList.addContent(getNavLinkClassUse());
   558             }
   559             if(configuration.createtree) {
   560                 navList.addContent(getNavLinkTree());
   561             }
   562             if(!(configuration.nodeprecated ||
   563                      configuration.nodeprecatedlist)) {
   564                 navList.addContent(getNavLinkDeprecated());
   565             }
   566             if(configuration.createindex) {
   567                 navList.addContent(getNavLinkIndex());
   568             }
   569             if (!configuration.nohelp) {
   570                 navList.addContent(getNavLinkHelp());
   571             }
   572             navDiv.addContent(navList);
   573             Content aboutDiv = HtmlTree.DIV(HtmlStyle.aboutLanguage, getUserHeaderFooter(header));
   574             navDiv.addContent(aboutDiv);
   575             body.addContent(navDiv);
   576             Content ulNav = HtmlTree.UL(HtmlStyle.navList, getNavLinkPrevious());
   577             ulNav.addContent(getNavLinkNext());
   578             Content subDiv = HtmlTree.DIV(HtmlStyle.subNav, ulNav);
   579             Content ulFrames = HtmlTree.UL(HtmlStyle.navList, getNavShowLists());
   580             ulFrames.addContent(getNavHideLists(filename));
   581             subDiv.addContent(ulFrames);
   582             HtmlTree ulAllClasses = HtmlTree.UL(HtmlStyle.navList, getNavLinkClassIndex());
   583             ulAllClasses.addAttr(HtmlAttr.ID, allClassesId.toString());
   584             subDiv.addContent(ulAllClasses);
   585             subDiv.addContent(getAllClassesLinkScript(allClassesId.toString()));
   586             addSummaryDetailLinks(subDiv);
   587             if (header) {
   588                 subDiv.addContent(getMarkerAnchor("skip-navbar_top"));
   589                 body.addContent(subDiv);
   590                 body.addContent(HtmlConstants.END_OF_TOP_NAVBAR);
   591             } else {
   592                 subDiv.addContent(getMarkerAnchor("skip-navbar_bottom"));
   593                 body.addContent(subDiv);
   594                 body.addContent(HtmlConstants.END_OF_BOTTOM_NAVBAR);
   595             }
   596         }
   597     }
   599     /**
   600      * Get the word "NEXT" to indicate that no link is available.  Override
   601      * this method to customize next link.
   602      *
   603      * @return a content tree for the link
   604      */
   605     protected Content getNavLinkNext() {
   606         return getNavLinkNext(null);
   607     }
   609     /**
   610      * Get the word "PREV" to indicate that no link is available.  Override
   611      * this method to customize prev link.
   612      *
   613      * @return a content tree for the link
   614      */
   615     protected Content getNavLinkPrevious() {
   616         return getNavLinkPrevious(null);
   617     }
   619     /**
   620      * Do nothing. This is the default method.
   621      */
   622     protected void addSummaryDetailLinks(Content navDiv) {
   623     }
   625     /**
   626      * Get link to the "overview-summary.html" page.
   627      *
   628      * @return a content tree for the link
   629      */
   630     protected Content getNavLinkContents() {
   631         Content linkContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_SUMMARY),
   632                 overviewLabel, "", "");
   633         Content li = HtmlTree.LI(linkContent);
   634         return li;
   635     }
   637     /**
   638      * Get link to the "package-summary.html" page for the package passed.
   639      *
   640      * @param pkg Package to which link will be generated
   641      * @return a content tree for the link
   642      */
   643     protected Content getNavLinkPackage(PackageDoc pkg) {
   644         Content linkContent = getPackageLink(pkg,
   645                 packageLabel);
   646         Content li = HtmlTree.LI(linkContent);
   647         return li;
   648     }
   650     /**
   651      * Get the word "Package" , to indicate that link is not available here.
   652      *
   653      * @return a content tree for the link
   654      */
   655     protected Content getNavLinkPackage() {
   656         Content li = HtmlTree.LI(packageLabel);
   657         return li;
   658     }
   660     /**
   661      * Get the word "Use", to indicate that link is not available.
   662      *
   663      * @return a content tree for the link
   664      */
   665     protected Content getNavLinkClassUse() {
   666         Content li = HtmlTree.LI(useLabel);
   667         return li;
   668     }
   670     /**
   671      * Get link for previous file.
   672      *
   673      * @param prev File name for the prev link
   674      * @return a content tree for the link
   675      */
   676     public Content getNavLinkPrevious(DocPath prev) {
   677         Content li;
   678         if (prev != null) {
   679             li = HtmlTree.LI(getHyperLink(prev, prevLabel, "", ""));
   680         }
   681         else
   682             li = HtmlTree.LI(prevLabel);
   683         return li;
   684     }
   686     /**
   687      * Get link for next file.  If next is null, just print the label
   688      * without linking it anywhere.
   689      *
   690      * @param next File name for the next link
   691      * @return a content tree for the link
   692      */
   693     public Content getNavLinkNext(DocPath next) {
   694         Content li;
   695         if (next != null) {
   696             li = HtmlTree.LI(getHyperLink(next, nextLabel, "", ""));
   697         }
   698         else
   699             li = HtmlTree.LI(nextLabel);
   700         return li;
   701     }
   703     /**
   704      * Get "FRAMES" link, to switch to the frame version of the output.
   705      *
   706      * @param link File to be linked, "index.html"
   707      * @return a content tree for the link
   708      */
   709     protected Content getNavShowLists(DocPath link) {
   710         DocLink dl = new DocLink(link, path.getPath(), null);
   711         Content framesContent = getHyperLink(dl, framesLabel, "", "_top");
   712         Content li = HtmlTree.LI(framesContent);
   713         return li;
   714     }
   716     /**
   717      * Get "FRAMES" link, to switch to the frame version of the output.
   718      *
   719      * @return a content tree for the link
   720      */
   721     protected Content getNavShowLists() {
   722         return getNavShowLists(pathToRoot.resolve(DocPaths.INDEX));
   723     }
   725     /**
   726      * Get "NO FRAMES" link, to switch to the non-frame version of the output.
   727      *
   728      * @param link File to be linked
   729      * @return a content tree for the link
   730      */
   731     protected Content getNavHideLists(DocPath link) {
   732         Content noFramesContent = getHyperLink(link, noframesLabel, "", "_top");
   733         Content li = HtmlTree.LI(noFramesContent);
   734         return li;
   735     }
   737     /**
   738      * Get "Tree" link in the navigation bar. If there is only one package
   739      * specified on the command line, then the "Tree" link will be to the
   740      * only "package-tree.html" file otherwise it will be to the
   741      * "overview-tree.html" file.
   742      *
   743      * @return a content tree for the link
   744      */
   745     protected Content getNavLinkTree() {
   746         Content treeLinkContent;
   747         PackageDoc[] packages = configuration.root.specifiedPackages();
   748         if (packages.length == 1 && configuration.root.specifiedClasses().length == 0) {
   749             treeLinkContent = getHyperLink(pathString(packages[0],
   750                     DocPaths.PACKAGE_TREE), treeLabel,
   751                     "", "");
   752         } else {
   753             treeLinkContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
   754                     treeLabel, "", "");
   755         }
   756         Content li = HtmlTree.LI(treeLinkContent);
   757         return li;
   758     }
   760     /**
   761      * Get the overview tree link for the main tree.
   762      *
   763      * @param label the label for the link
   764      * @return a content tree for the link
   765      */
   766     protected Content getNavLinkMainTree(String label) {
   767         Content mainTreeContent = getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
   768                 new StringContent(label));
   769         Content li = HtmlTree.LI(mainTreeContent);
   770         return li;
   771     }
   773     /**
   774      * Get the word "Class", to indicate that class link is not available.
   775      *
   776      * @return a content tree for the link
   777      */
   778     protected Content getNavLinkClass() {
   779         Content li = HtmlTree.LI(classLabel);
   780         return li;
   781     }
   783     /**
   784      * Get "Deprecated" API link in the navigation bar.
   785      *
   786      * @return a content tree for the link
   787      */
   788     protected Content getNavLinkDeprecated() {
   789         Content linkContent = getHyperLink(pathToRoot.resolve(DocPaths.DEPRECATED_LIST),
   790                 deprecatedLabel, "", "");
   791         Content li = HtmlTree.LI(linkContent);
   792         return li;
   793     }
   795     /**
   796      * Get link for generated index. If the user has used "-splitindex"
   797      * command line option, then link to file "index-files/index-1.html" is
   798      * generated otherwise link to file "index-all.html" is generated.
   799      *
   800      * @return a content tree for the link
   801      */
   802     protected Content getNavLinkClassIndex() {
   803         Content allClassesContent = getHyperLink(pathToRoot.resolve(
   804                 DocPaths.ALLCLASSES_NOFRAME),
   805                 allclassesLabel, "", "");
   806         Content li = HtmlTree.LI(allClassesContent);
   807         return li;
   808     }
   810     /**
   811      * Get link for generated class index.
   812      *
   813      * @return a content tree for the link
   814      */
   815     protected Content getNavLinkIndex() {
   816         Content linkContent = getHyperLink(pathToRoot.resolve(
   817                 (configuration.splitindex
   818                     ? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
   819                     : DocPaths.INDEX_ALL)),
   820             indexLabel, "", "");
   821         Content li = HtmlTree.LI(linkContent);
   822         return li;
   823     }
   825     /**
   826      * Get help file link. If user has provided a help file, then generate a
   827      * link to the user given file, which is already copied to current or
   828      * destination directory.
   829      *
   830      * @return a content tree for the link
   831      */
   832     protected Content getNavLinkHelp() {
   833         String helpfile = configuration.helpfile;
   834         DocPath helpfilenm;
   835         if (helpfile.isEmpty()) {
   836             helpfilenm = DocPaths.HELP_DOC;
   837         } else {
   838             DocFile file = DocFile.createFileForInput(configuration, helpfile);
   839             helpfilenm = DocPath.create(file.getName());
   840         }
   841         Content linkContent = getHyperLink(pathToRoot.resolve(helpfilenm),
   842                 helpLabel, "", "");
   843         Content li = HtmlTree.LI(linkContent);
   844         return li;
   845     }
   847     /**
   848      * Get summary table header.
   849      *
   850      * @param header the header for the table
   851      * @param scope the scope of the headers
   852      * @return a content tree for the header
   853      */
   854     public Content getSummaryTableHeader(String[] header, String scope) {
   855         Content tr = new HtmlTree(HtmlTag.TR);
   856         int size = header.length;
   857         Content tableHeader;
   858         if (size == 1) {
   859             tableHeader = new StringContent(header[0]);
   860             tr.addContent(HtmlTree.TH(HtmlStyle.colOne, scope, tableHeader));
   861             return tr;
   862         }
   863         for (int i = 0; i < size; i++) {
   864             tableHeader = new StringContent(header[i]);
   865             if(i == 0)
   866                 tr.addContent(HtmlTree.TH(HtmlStyle.colFirst, scope, tableHeader));
   867             else if(i == (size - 1))
   868                 tr.addContent(HtmlTree.TH(HtmlStyle.colLast, scope, tableHeader));
   869             else
   870                 tr.addContent(HtmlTree.TH(scope, tableHeader));
   871         }
   872         return tr;
   873     }
   875     /**
   876      * Get table caption.
   877      *
   878      * @param rawText the caption for the table which could be raw Html
   879      * @return a content tree for the caption
   880      */
   881     public Content getTableCaption(String rawText) {
   882         Content title = new RawHtml(rawText);
   883         Content captionSpan = HtmlTree.SPAN(title);
   884         Content space = getSpace();
   885         Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, space);
   886         Content caption = HtmlTree.CAPTION(captionSpan);
   887         caption.addContent(tabSpan);
   888         return caption;
   889     }
   891     /**
   892      * Get the marker anchor which will be added to the documentation tree.
   893      *
   894      * @param anchorName the anchor name attribute
   895      * @return a content tree for the marker anchor
   896      */
   897     public Content getMarkerAnchor(String anchorName) {
   898         return getMarkerAnchor(anchorName, null);
   899     }
   901     /**
   902      * Get the marker anchor which will be added to the documentation tree.
   903      *
   904      * @param anchorName the anchor name attribute
   905      * @param anchorContent the content that should be added to the anchor
   906      * @return a content tree for the marker anchor
   907      */
   908     public Content getMarkerAnchor(String anchorName, Content anchorContent) {
   909         if (anchorContent == null)
   910             anchorContent = new Comment(" ");
   911         Content markerAnchor = HtmlTree.A_NAME(anchorName, anchorContent);
   912         return markerAnchor;
   913     }
   915     /**
   916      * Returns a packagename content.
   917      *
   918      * @param packageDoc the package to check
   919      * @return package name content
   920      */
   921     public Content getPackageName(PackageDoc packageDoc) {
   922         return packageDoc == null || packageDoc.name().length() == 0 ?
   923             defaultPackageLabel :
   924             getPackageLabel(packageDoc.name());
   925     }
   927     /**
   928      * Returns a package name label.
   929      *
   930      * @param packageName the package name
   931      * @return the package name content
   932      */
   933     public Content getPackageLabel(String packageName) {
   934         return new StringContent(packageName);
   935     }
   937     /**
   938      * Add package deprecation information to the documentation tree
   939      *
   940      * @param deprPkgs list of deprecated packages
   941      * @param headingKey the caption for the deprecated package table
   942      * @param tableSummary the summary for the deprecated package table
   943      * @param tableHeader table headers for the deprecated package table
   944      * @param contentTree the content tree to which the deprecated package table will be added
   945      */
   946     protected void addPackageDeprecatedAPI(List<Doc> deprPkgs, String headingKey,
   947             String tableSummary, String[] tableHeader, Content contentTree) {
   948         if (deprPkgs.size() > 0) {
   949             Content table = HtmlTree.TABLE(0, 3, 0, tableSummary,
   950                     getTableCaption(configuration.getText(headingKey)));
   951             table.addContent(getSummaryTableHeader(tableHeader, "col"));
   952             Content tbody = new HtmlTree(HtmlTag.TBODY);
   953             for (int i = 0; i < deprPkgs.size(); i++) {
   954                 PackageDoc pkg = (PackageDoc) deprPkgs.get(i);
   955                 HtmlTree td = HtmlTree.TD(HtmlStyle.colOne,
   956                         getPackageLink(pkg, getPackageName(pkg)));
   957                 if (pkg.tags("deprecated").length > 0) {
   958                     addInlineDeprecatedComment(pkg, pkg.tags("deprecated")[0], td);
   959                 }
   960                 HtmlTree tr = HtmlTree.TR(td);
   961                 if (i % 2 == 0) {
   962                     tr.addStyle(HtmlStyle.altColor);
   963                 } else {
   964                     tr.addStyle(HtmlStyle.rowColor);
   965                 }
   966                 tbody.addContent(tr);
   967             }
   968             table.addContent(tbody);
   969             Content li = HtmlTree.LI(HtmlStyle.blockList, table);
   970             Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
   971             contentTree.addContent(ul);
   972         }
   973     }
   975     /**
   976      * Return the path to the class page for a classdoc.
   977      *
   978      * @param cd   Class to which the path is requested.
   979      * @param name Name of the file(doesn't include path).
   980      */
   981     protected DocPath pathString(ClassDoc cd, DocPath name) {
   982         return pathString(cd.containingPackage(), name);
   983     }
   985     /**
   986      * Return path to the given file name in the given package. So if the name
   987      * passed is "Object.html" and the name of the package is "java.lang", and
   988      * if the relative path is "../.." then returned string will be
   989      * "../../java/lang/Object.html"
   990      *
   991      * @param pd Package in which the file name is assumed to be.
   992      * @param name File name, to which path string is.
   993      */
   994     protected DocPath pathString(PackageDoc pd, DocPath name) {
   995         return pathToRoot.resolve(DocPath.forPackage(pd).resolve(name));
   996     }
   998     /**
   999      * Return the link to the given package.
  1001      * @param pkg the package to link to.
  1002      * @param label the label for the link.
  1003      * @param isStrong true if the label should be strong.
  1004      * @return the link to the given package.
  1005      */
  1006     public String getPackageLinkString(PackageDoc pkg, String label,
  1007                                  boolean isStrong) {
  1008         return getPackageLinkString(pkg, label, isStrong, "");
  1011     /**
  1012      * Return the link to the given package.
  1014      * @param pkg the package to link to.
  1015      * @param label the label for the link.
  1016      * @param isStrong true if the label should be strong.
  1017      * @param style  the font of the package link label.
  1018      * @return the link to the given package.
  1019      */
  1020     public String getPackageLinkString(PackageDoc pkg, String label, boolean isStrong,
  1021             String style) {
  1022         boolean included = pkg != null && pkg.isIncluded();
  1023         if (! included) {
  1024             PackageDoc[] packages = configuration.packages;
  1025             for (int i = 0; i < packages.length; i++) {
  1026                 if (packages[i].equals(pkg)) {
  1027                     included = true;
  1028                     break;
  1032         if (included || pkg == null) {
  1033             return getHyperLinkString(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
  1034                                 label, isStrong, style);
  1035         } else {
  1036             DocLink crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
  1037             if (crossPkgLink != null) {
  1038                 return getHyperLinkString(crossPkgLink, label, isStrong, style);
  1039             } else {
  1040                 return label;
  1045     /**
  1046      * Return the link to the given package.
  1048      * @param pkg the package to link to.
  1049      * @param label the label for the link.
  1050      * @return a content tree for the package link.
  1051      */
  1052     public Content getPackageLink(PackageDoc pkg, String label) {
  1053         return getPackageLink(pkg, new StringContent(label));
  1056     /**
  1057      * Return the link to the given package.
  1059      * @param pkg the package to link to.
  1060      * @param label the label for the link.
  1061      * @return a content tree for the package link.
  1062      */
  1063     public Content getPackageLink(PackageDoc pkg, Content label) {
  1064         boolean included = pkg != null && pkg.isIncluded();
  1065         if (! included) {
  1066             PackageDoc[] packages = configuration.packages;
  1067             for (int i = 0; i < packages.length; i++) {
  1068                 if (packages[i].equals(pkg)) {
  1069                     included = true;
  1070                     break;
  1074         if (included || pkg == null) {
  1075             return getHyperLink(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
  1076                     label);
  1077         } else {
  1078             DocLink crossPkgLink = getCrossPackageLink(Util.getPackageName(pkg));
  1079             if (crossPkgLink != null) {
  1080                 return getHyperLink(crossPkgLink, label);
  1081             } else {
  1082                 return label;
  1087     public Content italicsClassName(ClassDoc cd, boolean qual) {
  1088         Content name = new StringContent((qual)? cd.qualifiedName(): cd.name());
  1089         return (cd.isInterface())?  HtmlTree.I(name): name;
  1092     /**
  1093      * Add the link to the content tree.
  1095      * @param doc program element doc for which the link will be added
  1096      * @param label label for the link
  1097      * @param htmltree the content tree to which the link will be added
  1098      */
  1099     public void addSrcLink(ProgramElementDoc doc, Content label, Content htmltree) {
  1100         if (doc == null) {
  1101             return;
  1103         ClassDoc cd = doc.containingClass();
  1104         if (cd == null) {
  1105             //d must be a class doc since in has no containing class.
  1106             cd = (ClassDoc) doc;
  1108         DocPath href = pathToRoot
  1109                 .resolve(DocPaths.SOURCE_OUTPUT)
  1110                 .resolve(DocPath.forClass(cd));
  1111         Content linkContent = getHyperLink(href.fragment(SourceToHTMLConverter.getAnchorName(doc)), label, "", "");
  1112         htmltree.addContent(linkContent);
  1115     /**
  1116      * Return the link to the given class.
  1118      * @param linkInfo the information about the link.
  1120      * @return the link for the given class.
  1121      */
  1122     public Content getLink(LinkInfoImpl linkInfo) {
  1123         LinkFactoryImpl factory = new LinkFactoryImpl(this);
  1124         Content link = factory.getLink(linkInfo);
  1125         displayLength += linkInfo.displayLength;
  1126         return link;
  1129     /**
  1130      * Return the type parameters for the given class.
  1132      * @param linkInfo the information about the link.
  1133      * @return the type for the given class.
  1134      */
  1135     public Content getTypeParameterLinks(LinkInfoImpl linkInfo) {
  1136         LinkFactoryImpl factory = new LinkFactoryImpl(this);
  1137         return factory.getTypeParameterLinks(linkInfo, false);
  1140     /*************************************************************
  1141      * Return a class cross link to external class documentation.
  1142      * The name must be fully qualified to determine which package
  1143      * the class is in.  The -link option does not allow users to
  1144      * link to external classes in the "default" package.
  1146      * @param qualifiedClassName the qualified name of the external class.
  1147      * @param refMemName the name of the member being referenced.  This should
  1148      * be null or empty string if no member is being referenced.
  1149      * @param label the label for the external link.
  1150      * @param strong true if the link should be strong.
  1151      * @param style the style of the link.
  1152      * @param code true if the label should be code font.
  1153      */
  1154     public Content getCrossClassLink(String qualifiedClassName, String refMemName,
  1155                                     Content label, boolean strong, String style,
  1156                                     boolean code) {
  1157         String className = "";
  1158         String packageName = qualifiedClassName == null ? "" : qualifiedClassName;
  1159         int periodIndex;
  1160         while ((periodIndex = packageName.lastIndexOf('.')) != -1) {
  1161             className = packageName.substring(periodIndex + 1, packageName.length()) +
  1162                 (className.length() > 0 ? "." + className : "");
  1163             Content defaultLabel = new StringContent(className);
  1164             if (code)
  1165                 defaultLabel = HtmlTree.CODE(defaultLabel);
  1166             packageName = packageName.substring(0, periodIndex);
  1167             if (getCrossPackageLink(packageName) != null) {
  1168                 //The package exists in external documentation, so link to the external
  1169                 //class (assuming that it exists).  This is definitely a limitation of
  1170                 //the -link option.  There are ways to determine if an external package
  1171                 //exists, but no way to determine if the external class exists.  We just
  1172                 //have to assume that it does.
  1173                 DocLink link = configuration.extern.getExternalLink(packageName, pathToRoot,
  1174                                 className + ".html", refMemName);
  1175                 return getHyperLink(link,
  1176                     (label == null) || label.isEmpty() ? defaultLabel : label,
  1177                     strong, style,
  1178                     configuration.getText("doclet.Href_Class_Or_Interface_Title", packageName),
  1179                     "");
  1182         return null;
  1185     public boolean isClassLinkable(ClassDoc cd) {
  1186         if (cd.isIncluded()) {
  1187             return configuration.isGeneratedDoc(cd);
  1189         return configuration.extern.isExternal(cd);
  1192     public DocLink getCrossPackageLink(String pkgName) {
  1193         return configuration.extern.getExternalLink(pkgName, pathToRoot,
  1194             DocPaths.PACKAGE_SUMMARY.getPath());
  1197     /**
  1198      * Get the class link.
  1200      * @param context the id of the context where the link will be added
  1201      * @param cd the class doc to link to
  1202      * @return a content tree for the link
  1203      */
  1204     public Content getQualifiedClassLink(LinkInfoImpl.Kind context, ClassDoc cd) {
  1205         return getLink(new LinkInfoImpl(configuration, context, cd)
  1206                 .label(configuration.getClassName(cd)));
  1209     /**
  1210      * Add the class link.
  1212      * @param context the id of the context where the link will be added
  1213      * @param cd the class doc to link to
  1214      * @param contentTree the content tree to which the link will be added
  1215      */
  1216     public void addPreQualifiedClassLink(LinkInfoImpl.Kind context, ClassDoc cd, Content contentTree) {
  1217         addPreQualifiedClassLink(context, cd, false, contentTree);
  1220     /**
  1221      * Retrieve the class link with the package portion of the label in
  1222      * plain text.  If the qualifier is excluded, it will not be included in the
  1223      * link label.
  1225      * @param cd the class to link to.
  1226      * @param isStrong true if the link should be strong.
  1227      * @return the link with the package portion of the label in plain text.
  1228      */
  1229     public Content getPreQualifiedClassLink(LinkInfoImpl.Kind context,
  1230             ClassDoc cd, boolean isStrong) {
  1231         ContentBuilder classlink = new ContentBuilder();
  1232         PackageDoc pd = cd.containingPackage();
  1233         if (pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
  1234             classlink.addContent(getPkgName(cd));
  1236         classlink.addContent(getLink(new LinkInfoImpl(configuration,
  1237                 context, cd).label(cd.name()).strong(isStrong)));
  1238         return classlink;
  1241     /**
  1242      * Add the class link with the package portion of the label in
  1243      * plain text. If the qualifier is excluded, it will not be included in the
  1244      * link label.
  1246      * @param context the id of the context where the link will be added
  1247      * @param cd the class to link to
  1248      * @param isStrong true if the link should be strong
  1249      * @param contentTree the content tree to which the link with be added
  1250      */
  1251     public void addPreQualifiedClassLink(LinkInfoImpl.Kind context,
  1252             ClassDoc cd, boolean isStrong, Content contentTree) {
  1253         PackageDoc pd = cd.containingPackage();
  1254         if(pd != null && ! configuration.shouldExcludeQualifier(pd.name())) {
  1255             contentTree.addContent(getPkgName(cd));
  1257         contentTree.addContent(getLink(new LinkInfoImpl(configuration,
  1258                 context, cd).label(cd.name()).strong(isStrong)));
  1261     /**
  1262      * Add the class link, with only class name as the strong link and prefixing
  1263      * plain package name.
  1265      * @param context the id of the context where the link will be added
  1266      * @param cd the class to link to
  1267      * @param contentTree the content tree to which the link with be added
  1268      */
  1269     public void addPreQualifiedStrongClassLink(LinkInfoImpl.Kind context, ClassDoc cd, Content contentTree) {
  1270         addPreQualifiedClassLink(context, cd, true, contentTree);
  1273     /**
  1274      * Get the link for the given member.
  1276      * @param context the id of the context where the link will be added
  1277      * @param doc the member being linked to
  1278      * @param label the label for the link
  1279      * @return a content tree for the doc link
  1280      */
  1281     public Content getDocLink(LinkInfoImpl.Kind context, MemberDoc doc, String label) {
  1282         return getDocLink(context, doc.containingClass(), doc,
  1283                 new StringContent(label));
  1286     /**
  1287      * Return the link for the given member.
  1289      * @param context the id of the context where the link will be printed.
  1290      * @param doc the member being linked to.
  1291      * @param label the label for the link.
  1292      * @param strong true if the link should be strong.
  1293      * @return the link for the given member.
  1294      */
  1295     public Content getDocLink(LinkInfoImpl.Kind context, MemberDoc doc, String label,
  1296             boolean strong) {
  1297         return getDocLink(context, doc.containingClass(), doc, label, strong);
  1300     /**
  1301      * Return the link for the given member.
  1303      * @param context the id of the context where the link will be printed.
  1304      * @param classDoc the classDoc that we should link to.  This is not
  1305      *                 necessarily equal to doc.containingClass().  We may be
  1306      *                 inheriting comments.
  1307      * @param doc the member being linked to.
  1308      * @param label the label for the link.
  1309      * @param strong true if the link should be strong.
  1310      * @return the link for the given member.
  1311      */
  1312     public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
  1313             String label, boolean strong) {
  1314         return getDocLink(context, classDoc, doc, label, strong, false);
  1317    /**
  1318      * Return the link for the given member.
  1320      * @param context the id of the context where the link will be printed.
  1321      * @param classDoc the classDoc that we should link to.  This is not
  1322      *                 necessarily equal to doc.containingClass().  We may be
  1323      *                 inheriting comments.
  1324      * @param doc the member being linked to.
  1325      * @param label the label for the link.
  1326      * @param strong true if the link should be strong.
  1327      * @param isProperty true if the doc parameter is a JavaFX property.
  1328      * @return the link for the given member.
  1329      */
  1330     public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
  1331             String label, boolean strong, boolean isProperty) {
  1332         return getDocLink(context, classDoc, doc, new RawHtml(label), strong, isProperty);
  1335     public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
  1336             Content label, boolean strong, boolean isProperty) {
  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(getAnchor(emd, isProperty)).strong(strong));
  1344         } else if (doc instanceof MemberDoc) {
  1345             return getLink(new LinkInfoImpl(configuration, context, classDoc)
  1346                 .label(label).where(doc.name()).strong(strong));
  1347         } else {
  1348             return label;
  1352     /**
  1353      * Return the link for the given member.
  1355      * @param context the id of the context where the link will be added
  1356      * @param classDoc the classDoc that we should link to.  This is not
  1357      *                 necessarily equal to doc.containingClass().  We may be
  1358      *                 inheriting comments
  1359      * @param doc the member being linked to
  1360      * @param label the label for the link
  1361      * @return the link for the given member
  1362      */
  1363     public Content getDocLink(LinkInfoImpl.Kind context, ClassDoc classDoc, MemberDoc doc,
  1364             Content label) {
  1365         if (! (doc.isIncluded() ||
  1366             Util.isLinkable(classDoc, configuration))) {
  1367             return label;
  1368         } else if (doc instanceof ExecutableMemberDoc) {
  1369             ExecutableMemberDoc emd = (ExecutableMemberDoc) doc;
  1370             return getLink(new LinkInfoImpl(configuration, context, classDoc)
  1371                 .label(label).where(getAnchor(emd)));
  1372         } else if (doc instanceof MemberDoc) {
  1373             return getLink(new LinkInfoImpl(configuration, context, classDoc)
  1374                 .label(label).where(doc.name()));
  1375         } else {
  1376             return label;
  1380     public String getAnchor(ExecutableMemberDoc emd) {
  1381         return getAnchor(emd, false);
  1384     public String getAnchor(ExecutableMemberDoc emd, boolean isProperty) {
  1385         if (isProperty) {
  1386             return emd.name();
  1388         StringBuilder signature = new StringBuilder(emd.signature());
  1389         StringBuilder signatureParsed = new StringBuilder();
  1390         int counter = 0;
  1391         for (int i = 0; i < signature.length(); i++) {
  1392             char c = signature.charAt(i);
  1393             if (c == '<') {
  1394                 counter++;
  1395             } else if (c == '>') {
  1396                 counter--;
  1397             } else if (counter == 0) {
  1398                 signatureParsed.append(c);
  1401         return emd.name() + signatureParsed.toString();
  1404     public String seeTagToString(SeeTag see) {
  1405         String tagName = see.name();
  1406         if (! (tagName.startsWith("@link") || tagName.equals("@see"))) {
  1407             return "";
  1410         String seetext = replaceDocRootDir(see.text());
  1412         //Check if @see is an href or "string"
  1413         if (seetext.startsWith("<") || seetext.startsWith("\"")) {
  1414             return seetext;
  1417         boolean plain = tagName.equalsIgnoreCase("@linkplain");
  1418         Content label = plainOrCode(plain, new RawHtml(see.label()));
  1420         //The text from the @see tag.  We will output this text when a label is not specified.
  1421         Content text = plainOrCode(plain, new RawHtml(seetext));
  1423         ClassDoc refClass = see.referencedClass();
  1424         String refClassName = see.referencedClassName();
  1425         MemberDoc refMem = see.referencedMember();
  1426         String refMemName = see.referencedMemberName();
  1428         if (refClass == null) {
  1429             //@see is not referencing an included class
  1430             PackageDoc refPackage = see.referencedPackage();
  1431             if (refPackage != null && refPackage.isIncluded()) {
  1432                 //@see is referencing an included package
  1433                 if (label.isEmpty())
  1434                     label = plainOrCode(plain, new StringContent(refPackage.name()));
  1435                 return getPackageLink(refPackage, label).toString();
  1436             } else {
  1437                 //@see is not referencing an included class or package.  Check for cross links.
  1438                 Content classCrossLink;
  1439                 DocLink packageCrossLink = getCrossPackageLink(refClassName);
  1440                 if (packageCrossLink != null) {
  1441                     //Package cross link found
  1442                     return getHyperLink(packageCrossLink,
  1443                         (label.isEmpty() ? text : label)).toString();
  1444                 } else if ((classCrossLink = getCrossClassLink(refClassName,
  1445                         refMemName, label, false, "", !plain)) != null) {
  1446                     //Class cross link found (possibly to a member in the class)
  1447                     return classCrossLink.toString();
  1448                 } else {
  1449                     //No cross link found so print warning
  1450                     configuration.getDocletSpecificMsg().warning(see.position(), "doclet.see.class_or_package_not_found",
  1451                             tagName, seetext);
  1452                     return (label.isEmpty() ? text: label).toString();
  1455         } else if (refMemName == null) {
  1456             // Must be a class reference since refClass is not null and refMemName is null.
  1457             if (label.isEmpty()) {
  1458                 label = plainOrCode(plain, new StringContent(refClass.name()));
  1460             return getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.DEFAULT, refClass)
  1461                     .label(label)).toString();
  1462         } else if (refMem == null) {
  1463             // Must be a member reference since refClass is not null and refMemName is not null.
  1464             // However, refMem is null, so this referenced member does not exist.
  1465             return (label.isEmpty() ? text: label).toString();
  1466         } else {
  1467             // Must be a member reference since refClass is not null and refMemName is not null.
  1468             // refMem is not null, so this @see tag must be referencing a valid member.
  1469             ClassDoc containing = refMem.containingClass();
  1470             if (see.text().trim().startsWith("#") &&
  1471                 ! (containing.isPublic() ||
  1472                 Util.isLinkable(containing, configuration))) {
  1473                 // Since the link is relative and the holder is not even being
  1474                 // documented, this must be an inherited link.  Redirect it.
  1475                 // The current class either overrides the referenced member or
  1476                 // inherits it automatically.
  1477                 if (this instanceof ClassWriterImpl) {
  1478                     containing = ((ClassWriterImpl) this).getClassDoc();
  1479                 } else if (!containing.isPublic()){
  1480                     configuration.getDocletSpecificMsg().warning(
  1481                         see.position(), "doclet.see.class_or_package_not_accessible",
  1482                         tagName, containing.qualifiedName());
  1483                 } else {
  1484                     configuration.getDocletSpecificMsg().warning(
  1485                         see.position(), "doclet.see.class_or_package_not_found",
  1486                         tagName, seetext);
  1489             if (configuration.currentcd != containing) {
  1490                 refMemName = containing.name() + "." + refMemName;
  1492             if (refMem instanceof ExecutableMemberDoc) {
  1493                 if (refMemName.indexOf('(') < 0) {
  1494                     refMemName += ((ExecutableMemberDoc)refMem).signature();
  1498             text = plainOrCode(plain, new StringContent(refMemName));
  1500             return getDocLink(LinkInfoImpl.Kind.SEE_TAG, containing,
  1501                 refMem, (label.isEmpty() ? text: label).toString(), false).toString();
  1505     private String plainOrCodeText(boolean plain, String text) {
  1506         return (plain || text.isEmpty()) ? text : codeText(text);
  1509     private Content plainOrCode(boolean plain, Content body) {
  1510         return (plain || body.isEmpty()) ? body : HtmlTree.CODE(body);
  1513     /**
  1514      * Add the inline comment.
  1516      * @param doc the doc for which the inline comment will be added
  1517      * @param tag the inline tag to be added
  1518      * @param htmltree the content tree to which the comment will be added
  1519      */
  1520     public void addInlineComment(Doc doc, Tag tag, Content htmltree) {
  1521         addCommentTags(doc, tag, tag.inlineTags(), false, false, htmltree);
  1524     /**
  1525      * Add the inline deprecated comment.
  1527      * @param doc the doc for which the inline deprecated comment will be added
  1528      * @param tag the inline tag to be added
  1529      * @param htmltree the content tree to which the comment will be added
  1530      */
  1531     public void addInlineDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
  1532         addCommentTags(doc, tag.inlineTags(), true, false, htmltree);
  1535     /**
  1536      * Adds the summary content.
  1538      * @param doc the doc for which the summary will be generated
  1539      * @param htmltree the documentation tree to which the summary will be added
  1540      */
  1541     public void addSummaryComment(Doc doc, Content htmltree) {
  1542         addSummaryComment(doc, doc.firstSentenceTags(), htmltree);
  1545     /**
  1546      * Adds the summary content.
  1548      * @param doc the doc for which the summary will be generated
  1549      * @param firstSentenceTags the first sentence tags for the doc
  1550      * @param htmltree the documentation tree to which the summary will be added
  1551      */
  1552     public void addSummaryComment(Doc doc, Tag[] firstSentenceTags, Content htmltree) {
  1553         addCommentTags(doc, firstSentenceTags, false, true, htmltree);
  1556     public void addSummaryDeprecatedComment(Doc doc, Tag tag, Content htmltree) {
  1557         addCommentTags(doc, tag.firstSentenceTags(), true, true, htmltree);
  1560     /**
  1561      * Adds the inline comment.
  1563      * @param doc the doc for which the inline comments will be generated
  1564      * @param htmltree the documentation tree to which the inline comments will be added
  1565      */
  1566     public void addInlineComment(Doc doc, Content htmltree) {
  1567         addCommentTags(doc, doc.inlineTags(), false, false, htmltree);
  1570     /**
  1571      * Adds the comment tags.
  1573      * @param doc the doc for which the comment tags will be generated
  1574      * @param tags the first sentence tags for the doc
  1575      * @param depr true if it is deprecated
  1576      * @param first true if the first sentence tags should be added
  1577      * @param htmltree the documentation tree to which the comment tags will be added
  1578      */
  1579     private void addCommentTags(Doc doc, Tag[] tags, boolean depr,
  1580             boolean first, Content htmltree) {
  1581         addCommentTags(doc, null, tags, depr, first, htmltree);
  1584     /**
  1585      * Adds the comment tags.
  1587      * @param doc the doc for which the comment tags will be generated
  1588      * @param holderTag the block tag context for the inline tags
  1589      * @param tags the first sentence tags for the doc
  1590      * @param depr true if it is deprecated
  1591      * @param first true if the first sentence tags should be added
  1592      * @param htmltree the documentation tree to which the comment tags will be added
  1593      */
  1594     private void addCommentTags(Doc doc, Tag holderTag, Tag[] tags, boolean depr,
  1595             boolean first, Content htmltree) {
  1596         if(configuration.nocomment){
  1597             return;
  1599         Content div;
  1600         Content result = new RawHtml(commentTagsToString(holderTag, doc, tags, first));
  1601         if (depr) {
  1602             Content italic = HtmlTree.I(result);
  1603             div = HtmlTree.DIV(HtmlStyle.block, italic);
  1604             htmltree.addContent(div);
  1606         else {
  1607             div = HtmlTree.DIV(HtmlStyle.block, result);
  1608             htmltree.addContent(div);
  1610         if (tags.length == 0) {
  1611             htmltree.addContent(getSpace());
  1615     /**
  1616      * Converts inline tags and text to text strings, expanding the
  1617      * inline tags along the way.  Called wherever text can contain
  1618      * an inline tag, such as in comments or in free-form text arguments
  1619      * to non-inline tags.
  1621      * @param holderTag    specific tag where comment resides
  1622      * @param doc    specific doc where comment resides
  1623      * @param tags   array of text tags and inline tags (often alternating)
  1624      *               present in the text of interest for this doc
  1625      * @param isFirstSentence  true if text is first sentence
  1626      */
  1627     public String commentTagsToString(Tag holderTag, Doc doc, Tag[] tags,
  1628             boolean isFirstSentence) {
  1629         StringBuilder result = new StringBuilder();
  1630         boolean textTagChange = false;
  1631         // Array of all possible inline tags for this javadoc run
  1632         configuration.tagletManager.checkTags(doc, tags, true);
  1633         for (int i = 0; i < tags.length; i++) {
  1634             Tag tagelem = tags[i];
  1635             String tagName = tagelem.name();
  1636             if (tagelem instanceof SeeTag) {
  1637                 result.append(seeTagToString((SeeTag)tagelem));
  1638             } else if (! tagName.equals("Text")) {
  1639                 int originalLength = result.length();
  1640                 TagletOutput output = TagletWriter.getInlineTagOuput(
  1641                     configuration.tagletManager, holderTag,
  1642                     tagelem, getTagletWriterInstance(isFirstSentence));
  1643                 result.append(output == null ? "" : output.toString());
  1644                 if (originalLength == 0 && isFirstSentence && tagelem.name().equals("@inheritDoc") && result.length() > 0) {
  1645                     break;
  1646                 } else if (configuration.docrootparent.length() > 0 &&
  1647                         tagelem.name().equals("@docRoot") &&
  1648                         ((tags[i + 1]).text()).startsWith("/..")) {
  1649                     //If Xdocrootparent switch ON, set the flag to remove the /.. occurance after
  1650                     //{@docRoot} tag in the very next Text tag.
  1651                     textTagChange = true;
  1652                     continue;
  1653                 } else {
  1654                     continue;
  1656             } else {
  1657                 String text = tagelem.text();
  1658                 //If Xdocrootparent switch ON, remove the /.. occurance after {@docRoot} tag.
  1659                 if (textTagChange) {
  1660                     text = text.replaceFirst("/..", "");
  1661                     textTagChange = false;
  1663                 //This is just a regular text tag.  The text may contain html links (<a>)
  1664                 //or inline tag {@docRoot}, which will be handled as special cases.
  1665                 text = redirectRelativeLinks(tagelem.holder(), text);
  1667                 // Replace @docRoot only if not represented by an instance of DocRootTaglet,
  1668                 // that is, only if it was not present in a source file doc comment.
  1669                 // This happens when inserted by the doclet (a few lines
  1670                 // above in this method).  [It might also happen when passed in on the command
  1671                 // line as a text argument to an option (like -header).]
  1672                 text = replaceDocRootDir(text);
  1673                 if (isFirstSentence) {
  1674                     text = removeNonInlineHtmlTags(text);
  1676                 StringTokenizer lines = new StringTokenizer(text, "\r\n", true);
  1677                 StringBuilder textBuff = new StringBuilder();
  1678                 while (lines.hasMoreTokens()) {
  1679                     StringBuilder line = new StringBuilder(lines.nextToken());
  1680                     Util.replaceTabs(configuration, line);
  1681                     textBuff.append(line.toString());
  1683                 result.append(textBuff);
  1686         return result.toString();
  1689     /**
  1690      * Return true if relative links should not be redirected.
  1692      * @return Return true if a relative link should not be redirected.
  1693      */
  1694     private boolean shouldNotRedirectRelativeLinks() {
  1695         return  this instanceof AnnotationTypeWriter ||
  1696                 this instanceof ClassWriter ||
  1697                 this instanceof PackageSummaryWriter;
  1700     /**
  1701      * Suppose a piece of documentation has a relative link.  When you copy
  1702      * that documentation to another place such as the index or class-use page,
  1703      * that relative link will no longer work.  We should redirect those links
  1704      * so that they will work again.
  1705      * <p>
  1706      * Here is the algorithm used to fix the link:
  1707      * <p>
  1708      * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
  1709      * <p>
  1710      * For example, suppose com.sun.javadoc.RootDoc has this link:
  1711      * {@literal <a href="package-summary.html">The package Page</a> }
  1712      * <p>
  1713      * If this link appeared in the index, we would redirect
  1714      * the link like this:
  1716      * {@literal <a href="./com/sun/javadoc/package-summary.html">The package Page</a>}
  1718      * @param doc the Doc object whose documentation is being written.
  1719      * @param text the text being written.
  1721      * @return the text, with all the relative links redirected to work.
  1722      */
  1723     private String redirectRelativeLinks(Doc doc, String text) {
  1724         if (doc == null || shouldNotRedirectRelativeLinks()) {
  1725             return text;
  1728         DocPath redirectPathFromRoot;
  1729         if (doc instanceof ClassDoc) {
  1730             redirectPathFromRoot = DocPath.forPackage(((ClassDoc) doc).containingPackage());
  1731         } else if (doc instanceof MemberDoc) {
  1732             redirectPathFromRoot = DocPath.forPackage(((MemberDoc) doc).containingPackage());
  1733         } else if (doc instanceof PackageDoc) {
  1734             redirectPathFromRoot = DocPath.forPackage((PackageDoc) doc);
  1735         } else {
  1736             return text;
  1739         //Redirect all relative links.
  1740         int end, begin = text.toLowerCase().indexOf("<a");
  1741         if(begin >= 0){
  1742             StringBuilder textBuff = new StringBuilder(text);
  1744             while(begin >=0){
  1745                 if (textBuff.length() > begin + 2 && ! Character.isWhitespace(textBuff.charAt(begin+2))) {
  1746                     begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
  1747                     continue;
  1750                 begin = textBuff.indexOf("=", begin) + 1;
  1751                 end = textBuff.indexOf(">", begin +1);
  1752                 if(begin == 0){
  1753                     //Link has no equal symbol.
  1754                     configuration.root.printWarning(
  1755                         doc.position(),
  1756                         configuration.getText("doclet.malformed_html_link_tag", text));
  1757                     break;
  1759                 if (end == -1) {
  1760                     //Break without warning.  This <a> tag is not necessarily malformed.  The text
  1761                     //might be missing '>' character because the href has an inline tag.
  1762                     break;
  1764                 if (textBuff.substring(begin, end).indexOf("\"") != -1){
  1765                     begin = textBuff.indexOf("\"", begin) + 1;
  1766                     end = textBuff.indexOf("\"", begin +1);
  1767                     if (begin == 0 || end == -1){
  1768                         //Link is missing a quote.
  1769                         break;
  1772                 String relativeLink = textBuff.substring(begin, end);
  1773                 if (!(relativeLink.toLowerCase().startsWith("mailto:") ||
  1774                         relativeLink.toLowerCase().startsWith("http:") ||
  1775                         relativeLink.toLowerCase().startsWith("https:") ||
  1776                         relativeLink.toLowerCase().startsWith("file:"))) {
  1777                     relativeLink = "{@"+(new DocRootTaglet()).getName() + "}/"
  1778                         + redirectPathFromRoot.resolve(relativeLink).getPath();
  1779                     textBuff.replace(begin, end, relativeLink);
  1781                 begin = textBuff.toString().toLowerCase().indexOf("<a", begin + 1);
  1783             return textBuff.toString();
  1785         return text;
  1788     public String removeNonInlineHtmlTags(String text) {
  1789         if (text.indexOf('<') < 0) {
  1790             return text;
  1792         String noninlinetags[] = { "<ul>", "</ul>", "<ol>", "</ol>",
  1793                 "<dl>", "</dl>", "<table>", "</table>",
  1794                 "<tr>", "</tr>", "<td>", "</td>",
  1795                 "<th>", "</th>", "<p>", "</p>",
  1796                 "<li>", "</li>", "<dd>", "</dd>",
  1797                 "<dir>", "</dir>", "<dt>", "</dt>",
  1798                 "<h1>", "</h1>", "<h2>", "</h2>",
  1799                 "<h3>", "</h3>", "<h4>", "</h4>",
  1800                 "<h5>", "</h5>", "<h6>", "</h6>",
  1801                 "<pre>", "</pre>", "<menu>", "</menu>",
  1802                 "<listing>", "</listing>", "<hr>",
  1803                 "<blockquote>", "</blockquote>",
  1804                 "<center>", "</center>",
  1805                 "<UL>", "</UL>", "<OL>", "</OL>",
  1806                 "<DL>", "</DL>", "<TABLE>", "</TABLE>",
  1807                 "<TR>", "</TR>", "<TD>", "</TD>",
  1808                 "<TH>", "</TH>", "<P>", "</P>",
  1809                 "<LI>", "</LI>", "<DD>", "</DD>",
  1810                 "<DIR>", "</DIR>", "<DT>", "</DT>",
  1811                 "<H1>", "</H1>", "<H2>", "</H2>",
  1812                 "<H3>", "</H3>", "<H4>", "</H4>",
  1813                 "<H5>", "</H5>", "<H6>", "</H6>",
  1814                 "<PRE>", "</PRE>", "<MENU>", "</MENU>",
  1815                 "<LISTING>", "</LISTING>", "<HR>",
  1816                 "<BLOCKQUOTE>", "</BLOCKQUOTE>",
  1817                 "<CENTER>", "</CENTER>"
  1818         };
  1819         for (int i = 0; i < noninlinetags.length; i++) {
  1820             text = replace(text, noninlinetags[i], "");
  1822         return text;
  1825     public String replace(String text, String tobe, String by) {
  1826         while (true) {
  1827             int startindex = text.indexOf(tobe);
  1828             if (startindex < 0) {
  1829                 return text;
  1831             int endindex = startindex + tobe.length();
  1832             StringBuilder replaced = new StringBuilder();
  1833             if (startindex > 0) {
  1834                 replaced.append(text.substring(0, startindex));
  1836             replaced.append(by);
  1837             if (text.length() > endindex) {
  1838                 replaced.append(text.substring(endindex));
  1840             text = replaced.toString();
  1844     /**
  1845      * Returns a link to the stylesheet file.
  1847      * @return an HtmlTree for the lINK tag which provides the stylesheet location
  1848      */
  1849     public HtmlTree getStyleSheetProperties() {
  1850         String stylesheetfile = configuration.stylesheetfile;
  1851         DocPath stylesheet;
  1852         if (stylesheetfile.isEmpty()) {
  1853             stylesheet = DocPaths.STYLESHEET;
  1854         } else {
  1855             DocFile file = DocFile.createFileForInput(configuration, stylesheetfile);
  1856             stylesheet = DocPath.create(file.getName());
  1858         HtmlTree link = HtmlTree.LINK("stylesheet", "text/css",
  1859                 pathToRoot.resolve(stylesheet).getPath(),
  1860                 "Style");
  1861         return link;
  1864     /**
  1865      * Returns a link to the JavaScript file.
  1867      * @return an HtmlTree for the Script tag which provides the JavaScript location
  1868      */
  1869     public HtmlTree getScriptProperties() {
  1870         HtmlTree script = HtmlTree.SCRIPT("text/javascript",
  1871                 pathToRoot.resolve(DocPaths.JAVASCRIPT).getPath());
  1872         return script;
  1875     /**
  1876      * According to
  1877      * <cite>The Java&trade; Language Specification</cite>,
  1878      * all the outer classes and static nested classes are core classes.
  1879      */
  1880     public boolean isCoreClass(ClassDoc cd) {
  1881         return cd.containingClass() == null || cd.isStatic();
  1884     /**
  1885      * Adds the annotatation types for the given packageDoc.
  1887      * @param packageDoc the package to write annotations for.
  1888      * @param htmltree the documentation tree to which the annotation info will be
  1889      *        added
  1890      */
  1891     public void addAnnotationInfo(PackageDoc packageDoc, Content htmltree) {
  1892         addAnnotationInfo(packageDoc, packageDoc.annotations(), htmltree);
  1895     /**
  1896      * Add the annotation types of the executable receiver.
  1898      * @param method the executable to write the receiver annotations for.
  1899      * @param descList list of annotation description.
  1900      * @param htmltree the documentation tree to which the annotation info will be
  1901      *        added
  1902      */
  1903     public void addReceiverAnnotationInfo(ExecutableMemberDoc method, AnnotationDesc[] descList,
  1904             Content htmltree) {
  1905         addAnnotationInfo(0, method, descList, false, htmltree);
  1908     /**
  1909      * Adds the annotatation types for the given doc.
  1911      * @param doc the package to write annotations for
  1912      * @param htmltree the content tree to which the annotation types will be added
  1913      */
  1914     public void addAnnotationInfo(ProgramElementDoc doc, Content htmltree) {
  1915         addAnnotationInfo(doc, doc.annotations(), htmltree);
  1918     /**
  1919      * Add the annotatation types for the given doc and parameter.
  1921      * @param indent the number of spaces to indent the parameters.
  1922      * @param doc the doc to write annotations for.
  1923      * @param param the parameter to write annotations for.
  1924      * @param tree the content tree to which the annotation types will be added
  1925      */
  1926     public boolean addAnnotationInfo(int indent, Doc doc, Parameter param,
  1927             Content tree) {
  1928         return addAnnotationInfo(indent, doc, param.annotations(), false, tree);
  1931     /**
  1932      * Adds the annotatation types for the given doc.
  1934      * @param doc the doc to write annotations for.
  1935      * @param descList the array of {@link AnnotationDesc}.
  1936      * @param htmltree the documentation tree to which the annotation info will be
  1937      *        added
  1938      */
  1939     private void addAnnotationInfo(Doc doc, AnnotationDesc[] descList,
  1940             Content htmltree) {
  1941         addAnnotationInfo(0, doc, descList, true, htmltree);
  1944     /**
  1945      * Adds the annotatation types for the given doc.
  1947      * @param indent the number of extra spaces to indent the annotations.
  1948      * @param doc the doc to write annotations for.
  1949      * @param descList the array of {@link AnnotationDesc}.
  1950      * @param htmltree the documentation tree to which the annotation info will be
  1951      *        added
  1952      */
  1953     private boolean addAnnotationInfo(int indent, Doc doc,
  1954             AnnotationDesc[] descList, boolean lineBreak, Content htmltree) {
  1955         List<String> annotations = getAnnotations(indent, descList, lineBreak);
  1956         String sep ="";
  1957         if (annotations.size() == 0) {
  1958             return false;
  1960         Content annotationContent;
  1961         for (Iterator<String> iter = annotations.iterator(); iter.hasNext();) {
  1962             htmltree.addContent(sep);
  1963             annotationContent = new RawHtml(iter.next());
  1964             htmltree.addContent(annotationContent);
  1965             sep = " ";
  1967         return true;
  1970    /**
  1971      * Return the string representations of the annotation types for
  1972      * the given doc.
  1974      * @param indent the number of extra spaces to indent the annotations.
  1975      * @param descList the array of {@link AnnotationDesc}.
  1976      * @param linkBreak if true, add new line between each member value.
  1977      * @return an array of strings representing the annotations being
  1978      *         documented.
  1979      */
  1980     private List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak) {
  1981         return getAnnotations(indent, descList, linkBreak, true);
  1984     /**
  1985      * Return the string representations of the annotation types for
  1986      * the given doc.
  1988      * A {@code null} {@code elementType} indicates that all the
  1989      * annotations should be returned without any filtering.
  1991      * @param indent the number of extra spaces to indent the annotations.
  1992      * @param descList the array of {@link AnnotationDesc}.
  1993      * @param linkBreak if true, add new line between each member value.
  1994      * @param elementType the type of targeted element (used for filtering
  1995      *        type annotations from declaration annotations)
  1996      * @return an array of strings representing the annotations being
  1997      *         documented.
  1998      */
  1999     public List<String> getAnnotations(int indent, AnnotationDesc[] descList, boolean linkBreak,
  2000             boolean isJava5DeclarationLocation) {
  2001         List<String> results = new ArrayList<String>();
  2002         StringBuilder annotation;
  2003         for (int i = 0; i < descList.length; i++) {
  2004             AnnotationTypeDoc annotationDoc = descList[i].annotationType();
  2005             // If an annotation is not documented, do not add it to the list. If
  2006             // the annotation is of a repeatable type, and if it is not documented
  2007             // and also if its container annotation is not documented, do not add it
  2008             // to the list. If an annotation of a repeatable type is not documented
  2009             // but its container is documented, it will be added to the list.
  2010             if (! Util.isDocumentedAnnotation(annotationDoc) &&
  2011                     (!isAnnotationDocumented && !isContainerDocumented)) {
  2012                 continue;
  2014             /* TODO: check logic here to correctly handle declaration
  2015              * and type annotations.
  2016             if  (Util.isDeclarationAnnotation(annotationDoc, isJava5DeclarationLocation)) {
  2017                 continue;
  2018             }*/
  2019             annotation = new StringBuilder();
  2020             isAnnotationDocumented = false;
  2021             LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
  2022                 LinkInfoImpl.Kind.ANNOTATION, annotationDoc);
  2023             AnnotationDesc.ElementValuePair[] pairs = descList[i].elementValues();
  2024             // If the annotation is synthesized, do not print the container.
  2025             if (descList[i].isSynthesized()) {
  2026                 for (int j = 0; j < pairs.length; j++) {
  2027                     AnnotationValue annotationValue = pairs[j].value();
  2028                     List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
  2029                     if (annotationValue.value() instanceof AnnotationValue[]) {
  2030                         AnnotationValue[] annotationArray =
  2031                                 (AnnotationValue[]) annotationValue.value();
  2032                         annotationTypeValues.addAll(Arrays.asList(annotationArray));
  2033                     } else {
  2034                         annotationTypeValues.add(annotationValue);
  2036                     String sep = "";
  2037                     for (AnnotationValue av : annotationTypeValues) {
  2038                         annotation.append(sep);
  2039                         annotation.append(annotationValueToString(av));
  2040                         sep = " ";
  2044             else if (isAnnotationArray(pairs)) {
  2045                 // If the container has 1 or more value defined and if the
  2046                 // repeatable type annotation is not documented, do not print
  2047                 // the container.
  2048                 if (pairs.length == 1 && isAnnotationDocumented) {
  2049                     AnnotationValue[] annotationArray =
  2050                             (AnnotationValue[]) (pairs[0].value()).value();
  2051                     List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
  2052                     annotationTypeValues.addAll(Arrays.asList(annotationArray));
  2053                     String sep = "";
  2054                     for (AnnotationValue av : annotationTypeValues) {
  2055                         annotation.append(sep);
  2056                         annotation.append(annotationValueToString(av));
  2057                         sep = " ";
  2060                 // If the container has 1 or more value defined and if the
  2061                 // repeatable type annotation is not documented, print the container.
  2062                 else {
  2063                     addAnnotations(annotationDoc, linkInfo, annotation, pairs,
  2064                         indent, false);
  2067             else {
  2068                 addAnnotations(annotationDoc, linkInfo, annotation, pairs,
  2069                         indent, linkBreak);
  2071             annotation.append(linkBreak ? DocletConstants.NL : "");
  2072             results.add(annotation.toString());
  2074         return results;
  2077     /**
  2078      * Add annotation to the annotation string.
  2080      * @param annotationDoc the annotation being documented
  2081      * @param linkInfo the information about the link
  2082      * @param annotation the annotation string to which the annotation will be added
  2083      * @param pairs annotation type element and value pairs
  2084      * @param indent the number of extra spaces to indent the annotations.
  2085      * @param linkBreak if true, add new line between each member value
  2086      */
  2087     private void addAnnotations(AnnotationTypeDoc annotationDoc, LinkInfoImpl linkInfo,
  2088             StringBuilder annotation, AnnotationDesc.ElementValuePair[] pairs,
  2089             int indent, boolean linkBreak) {
  2090         linkInfo.label = new StringContent("@" + annotationDoc.name());
  2091         annotation.append(getLink(linkInfo));
  2092         if (pairs.length > 0) {
  2093             annotation.append('(');
  2094             for (int j = 0; j < pairs.length; j++) {
  2095                 if (j > 0) {
  2096                     annotation.append(",");
  2097                     if (linkBreak) {
  2098                         annotation.append(DocletConstants.NL);
  2099                         int spaces = annotationDoc.name().length() + 2;
  2100                         for (int k = 0; k < (spaces + indent); k++) {
  2101                             annotation.append(' ');
  2105                 annotation.append(getDocLink(LinkInfoImpl.Kind.ANNOTATION,
  2106                         pairs[j].element(), pairs[j].element().name(), false));
  2107                 annotation.append('=');
  2108                 AnnotationValue annotationValue = pairs[j].value();
  2109                 List<AnnotationValue> annotationTypeValues = new ArrayList<AnnotationValue>();
  2110                 if (annotationValue.value() instanceof AnnotationValue[]) {
  2111                     AnnotationValue[] annotationArray =
  2112                             (AnnotationValue[]) annotationValue.value();
  2113                     annotationTypeValues.addAll(Arrays.asList(annotationArray));
  2114                 } else {
  2115                     annotationTypeValues.add(annotationValue);
  2117                 annotation.append(annotationTypeValues.size() == 1 ? "" : "{");
  2118                 String sep = "";
  2119                 for (AnnotationValue av : annotationTypeValues) {
  2120                     annotation.append(sep);
  2121                     annotation.append(annotationValueToString(av));
  2122                     sep = ",";
  2124                 annotation.append(annotationTypeValues.size() == 1 ? "" : "}");
  2125                 isContainerDocumented = false;
  2127             annotation.append(")");
  2131     /**
  2132      * Check if the annotation contains an array of annotation as a value. This
  2133      * check is to verify if a repeatable type annotation is present or not.
  2135      * @param pairs annotation type element and value pairs
  2137      * @return true if the annotation contains an array of annotation as a value.
  2138      */
  2139     private boolean isAnnotationArray(AnnotationDesc.ElementValuePair[] pairs) {
  2140         AnnotationValue annotationValue;
  2141         for (int j = 0; j < pairs.length; j++) {
  2142             annotationValue = pairs[j].value();
  2143             if (annotationValue.value() instanceof AnnotationValue[]) {
  2144                 AnnotationValue[] annotationArray =
  2145                         (AnnotationValue[]) annotationValue.value();
  2146                 if (annotationArray.length > 1) {
  2147                     if (annotationArray[0].value() instanceof AnnotationDesc) {
  2148                         AnnotationTypeDoc annotationDoc =
  2149                                 ((AnnotationDesc) annotationArray[0].value()).annotationType();
  2150                         isContainerDocumented = true;
  2151                         if (Util.isDocumentedAnnotation(annotationDoc)) {
  2152                             isAnnotationDocumented = true;
  2154                         return true;
  2159         return false;
  2162     private String annotationValueToString(AnnotationValue annotationValue) {
  2163         if (annotationValue.value() instanceof Type) {
  2164             Type type = (Type) annotationValue.value();
  2165             if (type.asClassDoc() != null) {
  2166                 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
  2167                     LinkInfoImpl.Kind.ANNOTATION, type);
  2168                 linkInfo.label = new StringContent((type.asClassDoc().isIncluded() ?
  2169                     type.typeName() :
  2170                     type.qualifiedTypeName()) + type.dimension() + ".class");
  2171                 return getLink(linkInfo).toString();
  2172             } else {
  2173                 return type.typeName() + type.dimension() + ".class";
  2175         } else if (annotationValue.value() instanceof AnnotationDesc) {
  2176             List<String> list = getAnnotations(0,
  2177                 new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
  2178                     false);
  2179             StringBuilder buf = new StringBuilder();
  2180             for (String s: list) {
  2181                 buf.append(s);
  2183             return buf.toString();
  2184         } else if (annotationValue.value() instanceof MemberDoc) {
  2185             return getDocLink(LinkInfoImpl.Kind.ANNOTATION,
  2186                 (MemberDoc) annotationValue.value(),
  2187                 ((MemberDoc) annotationValue.value()).name(), false).toString();
  2188          } else {
  2189             return annotationValue.toString();
  2193     /**
  2194      * Return the configuation for this doclet.
  2196      * @return the configuration for this doclet.
  2197      */
  2198     public Configuration configuration() {
  2199         return configuration;

mercurial