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