1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,989 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.internal.toolkit;
1.30 +
1.31 +import java.io.*;
1.32 +import java.util.*;
1.33 +import java.util.regex.Matcher;
1.34 +import java.util.regex.Pattern;
1.35 +import javax.tools.JavaFileManager;
1.36 +
1.37 +import com.sun.javadoc.*;
1.38 +import com.sun.tools.javac.sym.Profiles;
1.39 +import com.sun.tools.javac.jvm.Profile;
1.40 +import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
1.41 +import com.sun.tools.doclets.internal.toolkit.taglets.*;
1.42 +import com.sun.tools.doclets.internal.toolkit.util.*;
1.43 +import com.sun.tools.javac.util.StringUtils;
1.44 +
1.45 +/**
1.46 + * Configure the output based on the options. Doclets should sub-class
1.47 + * Configuration, to configure and add their own options. This class contains
1.48 + * all user options which are supported by the 1.1 doclet and the standard
1.49 + * doclet.
1.50 + *
1.51 + * <p><b>This is NOT part of any supported API.
1.52 + * If you write code that depends on this, you do so at your own risk.
1.53 + * This code and its internal interfaces are subject to change or
1.54 + * deletion without notice.</b>
1.55 + *
1.56 + * @author Robert Field.
1.57 + * @author Atul Dambalkar.
1.58 + * @author Jamie Ho
1.59 + */
1.60 +public abstract class Configuration {
1.61 +
1.62 + /**
1.63 + * Exception used to report a problem during setOptions.
1.64 + */
1.65 + public static class Fault extends Exception {
1.66 + private static final long serialVersionUID = 0;
1.67 +
1.68 + Fault(String msg) {
1.69 + super(msg);
1.70 + }
1.71 +
1.72 + Fault(String msg, Exception cause) {
1.73 + super(msg, cause);
1.74 + }
1.75 + }
1.76 +
1.77 + /**
1.78 + * The factory for builders.
1.79 + */
1.80 + protected BuilderFactory builderFactory;
1.81 +
1.82 + /**
1.83 + * The taglet manager.
1.84 + */
1.85 + public TagletManager tagletManager;
1.86 +
1.87 + /**
1.88 + * The path to the builder XML input file.
1.89 + */
1.90 + public String builderXMLPath;
1.91 +
1.92 + /**
1.93 + * The default path to the builder XML.
1.94 + */
1.95 + private static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";
1.96 +
1.97 + /**
1.98 + * The path to Taglets
1.99 + */
1.100 + public String tagletpath = "";
1.101 +
1.102 + /**
1.103 + * This is true if option "-serialwarn" is used. Defualt value is false to
1.104 + * suppress excessive warnings about serial tag.
1.105 + */
1.106 + public boolean serialwarn = false;
1.107 +
1.108 + /**
1.109 + * The specified amount of space between tab stops.
1.110 + */
1.111 + public int sourcetab;
1.112 +
1.113 + public String tabSpaces;
1.114 +
1.115 + /**
1.116 + * True if we should generate browsable sources.
1.117 + */
1.118 + public boolean linksource = false;
1.119 +
1.120 + /**
1.121 + * True if command line option "-nosince" is used. Default value is
1.122 + * false.
1.123 + */
1.124 + public boolean nosince = false;
1.125 +
1.126 + /**
1.127 + * True if we should recursively copy the doc-file subdirectories
1.128 + */
1.129 + public boolean copydocfilesubdirs = false;
1.130 +
1.131 + /**
1.132 + * The META charset tag used for cross-platform viewing.
1.133 + */
1.134 + public String charset = "";
1.135 +
1.136 + /**
1.137 + * True if user wants to add member names as meta keywords.
1.138 + * Set to false because meta keywords are ignored in general
1.139 + * by most Internet search engines.
1.140 + */
1.141 + public boolean keywords = false;
1.142 +
1.143 + /**
1.144 + * The meta tag keywords instance.
1.145 + */
1.146 + public final MetaKeywords metakeywords = new MetaKeywords(this);
1.147 +
1.148 + /**
1.149 + * The list of doc-file subdirectories to exclude
1.150 + */
1.151 + protected Set<String> excludedDocFileDirs;
1.152 +
1.153 + /**
1.154 + * The list of qualifiers to exclude
1.155 + */
1.156 + protected Set<String> excludedQualifiers;
1.157 +
1.158 + /**
1.159 + * The Root of the generated Program Structure from the Doclet API.
1.160 + */
1.161 + public RootDoc root;
1.162 +
1.163 + /**
1.164 + * Destination directory name, in which doclet will generate the entire
1.165 + * documentation. Default is current directory.
1.166 + */
1.167 + public String destDirName = "";
1.168 +
1.169 + /**
1.170 + * Destination directory name, in which doclet will copy the doc-files to.
1.171 + */
1.172 + public String docFileDestDirName = "";
1.173 +
1.174 + /**
1.175 + * Encoding for this document. Default is default encoding for this
1.176 + * platform.
1.177 + */
1.178 + public String docencoding = null;
1.179 +
1.180 + /**
1.181 + * True if user wants to suppress descriptions and tags.
1.182 + */
1.183 + public boolean nocomment = false;
1.184 +
1.185 + /**
1.186 + * Encoding for this document. Default is default encoding for this
1.187 + * platform.
1.188 + */
1.189 + public String encoding = null;
1.190 +
1.191 + /**
1.192 + * Generate author specific information for all the classes if @author
1.193 + * tag is used in the doc comment and if -author option is used.
1.194 + * <code>showauthor</code> is set to true if -author option is used.
1.195 + * Default is don't show author information.
1.196 + */
1.197 + public boolean showauthor = false;
1.198 +
1.199 + /**
1.200 + * Generate documentation for JavaFX getters and setters automatically
1.201 + * by copying it from the appropriate property definition.
1.202 + */
1.203 + public boolean javafx = false;
1.204 +
1.205 + /**
1.206 + * Generate version specific information for the all the classes
1.207 + * if @version tag is used in the doc comment and if -version option is
1.208 + * used. <code>showversion</code> is set to true if -version option is
1.209 + * used.Default is don't show version information.
1.210 + */
1.211 + public boolean showversion = false;
1.212 +
1.213 + /**
1.214 + * Sourcepath from where to read the source files. Default is classpath.
1.215 + *
1.216 + */
1.217 + public String sourcepath = "";
1.218 +
1.219 + /**
1.220 + * Argument for command line option "-Xprofilespath".
1.221 + */
1.222 + public String profilespath = "";
1.223 +
1.224 + /**
1.225 + * Generate profiles documentation if profilespath is set and valid profiles
1.226 + * are present.
1.227 + */
1.228 + public boolean showProfiles = false;
1.229 +
1.230 + /**
1.231 + * Don't generate deprecated API information at all, if -nodeprecated
1.232 + * option is used. <code>nodepracted</code> is set to true if
1.233 + * -nodeprecated option is used. Default is generate deprected API
1.234 + * information.
1.235 + */
1.236 + public boolean nodeprecated = false;
1.237 +
1.238 + /**
1.239 + * The catalog of classes specified on the command-line
1.240 + */
1.241 + public ClassDocCatalog classDocCatalog;
1.242 +
1.243 + /**
1.244 + * Message Retriever for the doclet, to retrieve message from the resource
1.245 + * file for this Configuration, which is common for 1.1 and standard
1.246 + * doclets.
1.247 + *
1.248 + * TODO: Make this private!!!
1.249 + */
1.250 + public MessageRetriever message = null;
1.251 +
1.252 + /**
1.253 + * True if user wants to suppress time stamp in output.
1.254 + * Default is false.
1.255 + */
1.256 + public boolean notimestamp= false;
1.257 +
1.258 + /**
1.259 + * The package grouping instance.
1.260 + */
1.261 + public final Group group = new Group(this);
1.262 +
1.263 + /**
1.264 + * The tracker of external package links.
1.265 + */
1.266 + public final Extern extern = new Extern(this);
1.267 +
1.268 + /**
1.269 + * Return the build date for the doclet.
1.270 + */
1.271 + public abstract String getDocletSpecificBuildDate();
1.272 +
1.273 + /**
1.274 + * This method should be defined in all those doclets(configurations),
1.275 + * which want to derive themselves from this Configuration. This method
1.276 + * can be used to set its own command line options.
1.277 + *
1.278 + * @param options The array of option names and values.
1.279 + * @throws DocletAbortException
1.280 + */
1.281 + public abstract void setSpecificDocletOptions(String[][] options) throws Fault;
1.282 +
1.283 + /**
1.284 + * Return the doclet specific {@link MessageRetriever}
1.285 + * @return the doclet specific MessageRetriever.
1.286 + */
1.287 + public abstract MessageRetriever getDocletSpecificMsg();
1.288 +
1.289 + /**
1.290 + * A profiles object used to access profiles across various pages.
1.291 + */
1.292 + public Profiles profiles;
1.293 +
1.294 + /**
1.295 + * An map of the profiles to packages.
1.296 + */
1.297 + public Map<String,PackageDoc[]> profilePackages;
1.298 +
1.299 + /**
1.300 + * An array of the packages specified on the command-line merged
1.301 + * with the array of packages that contain the classes specified on the
1.302 + * command-line. The array is sorted.
1.303 + */
1.304 + public PackageDoc[] packages;
1.305 +
1.306 + /**
1.307 + * Constructor. Constructs the message retriever with resource file.
1.308 + */
1.309 + public Configuration() {
1.310 + message =
1.311 + new MessageRetriever(this,
1.312 + "com.sun.tools.doclets.internal.toolkit.resources.doclets");
1.313 + excludedDocFileDirs = new HashSet<String>();
1.314 + excludedQualifiers = new HashSet<String>();
1.315 + setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
1.316 + }
1.317 +
1.318 + /**
1.319 + * Return the builder factory for this doclet.
1.320 + *
1.321 + * @return the builder factory for this doclet.
1.322 + */
1.323 + public BuilderFactory getBuilderFactory() {
1.324 + if (builderFactory == null) {
1.325 + builderFactory = new BuilderFactory(this);
1.326 + }
1.327 + return builderFactory;
1.328 + }
1.329 +
1.330 + /**
1.331 + * This method should be defined in all those doclets
1.332 + * which want to inherit from this Configuration. This method
1.333 + * should return the number of arguments to the command line
1.334 + * option (including the option name). For example,
1.335 + * -notimestamp is a single-argument option, so this method would
1.336 + * return 1.
1.337 + *
1.338 + * @param option Command line option under consideration.
1.339 + * @return number of arguments to option (including the
1.340 + * option name). Zero return means option not known.
1.341 + * Negative value means error occurred.
1.342 + */
1.343 + public int optionLength(String option) {
1.344 + option = StringUtils.toLowerCase(option);
1.345 + if (option.equals("-author") ||
1.346 + option.equals("-docfilessubdirs") ||
1.347 + option.equals("-javafx") ||
1.348 + option.equals("-keywords") ||
1.349 + option.equals("-linksource") ||
1.350 + option.equals("-nocomment") ||
1.351 + option.equals("-nodeprecated") ||
1.352 + option.equals("-nosince") ||
1.353 + option.equals("-notimestamp") ||
1.354 + option.equals("-quiet") ||
1.355 + option.equals("-xnodate") ||
1.356 + option.equals("-version")) {
1.357 + return 1;
1.358 + } else if (option.equals("-d") ||
1.359 + option.equals("-docencoding") ||
1.360 + option.equals("-encoding") ||
1.361 + option.equals("-excludedocfilessubdir") ||
1.362 + option.equals("-link") ||
1.363 + option.equals("-sourcetab") ||
1.364 + option.equals("-noqualifier") ||
1.365 + option.equals("-output") ||
1.366 + option.equals("-sourcepath") ||
1.367 + option.equals("-tag") ||
1.368 + option.equals("-taglet") ||
1.369 + option.equals("-tagletpath") ||
1.370 + option.equals("-xprofilespath")) {
1.371 + return 2;
1.372 + } else if (option.equals("-group") ||
1.373 + option.equals("-linkoffline")) {
1.374 + return 3;
1.375 + } else {
1.376 + return -1; // indicate we don't know about it
1.377 + }
1.378 + }
1.379 +
1.380 + /**
1.381 + * Perform error checking on the given options.
1.382 + *
1.383 + * @param options the given options to check.
1.384 + * @param reporter the reporter used to report errors.
1.385 + */
1.386 + public abstract boolean validOptions(String options[][],
1.387 + DocErrorReporter reporter);
1.388 +
1.389 + private void initProfiles() throws IOException {
1.390 + if (profilespath.isEmpty())
1.391 + return;
1.392 +
1.393 + profiles = Profiles.read(new File(profilespath));
1.394 +
1.395 + // Group the packages to be documented by the lowest profile (if any)
1.396 + // in which each appears
1.397 + Map<Profile, List<PackageDoc>> interimResults =
1.398 + new EnumMap<Profile, List<PackageDoc>>(Profile.class);
1.399 + for (Profile p: Profile.values())
1.400 + interimResults.put(p, new ArrayList<PackageDoc>());
1.401 +
1.402 + for (PackageDoc pkg: packages) {
1.403 + if (nodeprecated && Util.isDeprecated(pkg)) {
1.404 + continue;
1.405 + }
1.406 + // the getProfile method takes a type name, not a package name,
1.407 + // but isn't particularly fussy about the simple name -- so just use *
1.408 + int i = profiles.getProfile(pkg.name().replace(".", "/") + "/*");
1.409 + Profile p = Profile.lookup(i);
1.410 + if (p != null) {
1.411 + List<PackageDoc> pkgs = interimResults.get(p);
1.412 + pkgs.add(pkg);
1.413 + }
1.414 + }
1.415 +
1.416 + // Build the profilePackages structure used by the doclet
1.417 + profilePackages = new HashMap<String,PackageDoc[]>();
1.418 + List<PackageDoc> prev = Collections.<PackageDoc>emptyList();
1.419 + int size;
1.420 + for (Map.Entry<Profile,List<PackageDoc>> e: interimResults.entrySet()) {
1.421 + Profile p = e.getKey();
1.422 + List<PackageDoc> pkgs = e.getValue();
1.423 + pkgs.addAll(prev); // each profile contains all lower profiles
1.424 + Collections.sort(pkgs);
1.425 + size = pkgs.size();
1.426 + // For a profile, if there are no packages to be documented, do not add
1.427 + // it to profilePackages map.
1.428 + if (size > 0)
1.429 + profilePackages.put(p.name, pkgs.toArray(new PackageDoc[pkgs.size()]));
1.430 + prev = pkgs;
1.431 + }
1.432 +
1.433 + // Generate profiles documentation if any profile contains any
1.434 + // of the packages to be documented.
1.435 + showProfiles = !prev.isEmpty();
1.436 + }
1.437 +
1.438 + private void initPackageArray() {
1.439 + Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
1.440 + ClassDoc[] classes = root.specifiedClasses();
1.441 + for (int i = 0; i < classes.length; i++) {
1.442 + set.add(classes[i].containingPackage());
1.443 + }
1.444 + ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
1.445 + Collections.sort(results);
1.446 + packages = results.toArray(new PackageDoc[] {});
1.447 + }
1.448 +
1.449 + /**
1.450 + * Set the command line options supported by this configuration.
1.451 + *
1.452 + * @param options the two dimensional array of options.
1.453 + */
1.454 + public void setOptions(String[][] options) throws Fault {
1.455 + LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
1.456 +
1.457 + // Some options, specifically -link and -linkoffline, require that
1.458 + // the output directory has already been created: so do that first.
1.459 + for (int oi = 0; oi < options.length; ++oi) {
1.460 + String[] os = options[oi];
1.461 + String opt = StringUtils.toLowerCase(os[0]);
1.462 + if (opt.equals("-d")) {
1.463 + destDirName = addTrailingFileSep(os[1]);
1.464 + docFileDestDirName = destDirName;
1.465 + ensureOutputDirExists();
1.466 + break;
1.467 + }
1.468 + }
1.469 +
1.470 + for (int oi = 0; oi < options.length; ++oi) {
1.471 + String[] os = options[oi];
1.472 + String opt = StringUtils.toLowerCase(os[0]);
1.473 + if (opt.equals("-docfilessubdirs")) {
1.474 + copydocfilesubdirs = true;
1.475 + } else if (opt.equals("-docencoding")) {
1.476 + docencoding = os[1];
1.477 + } else if (opt.equals("-encoding")) {
1.478 + encoding = os[1];
1.479 + } else if (opt.equals("-author")) {
1.480 + showauthor = true;
1.481 + } else if (opt.equals("-javafx")) {
1.482 + javafx = true;
1.483 + } else if (opt.equals("-nosince")) {
1.484 + nosince = true;
1.485 + } else if (opt.equals("-version")) {
1.486 + showversion = true;
1.487 + } else if (opt.equals("-nodeprecated")) {
1.488 + nodeprecated = true;
1.489 + } else if (opt.equals("-sourcepath")) {
1.490 + sourcepath = os[1];
1.491 + } else if ((opt.equals("-classpath") || opt.equals("-cp")) &&
1.492 + sourcepath.length() == 0) {
1.493 + sourcepath = os[1];
1.494 + } else if (opt.equals("-excludedocfilessubdir")) {
1.495 + addToSet(excludedDocFileDirs, os[1]);
1.496 + } else if (opt.equals("-noqualifier")) {
1.497 + addToSet(excludedQualifiers, os[1]);
1.498 + } else if (opt.equals("-linksource")) {
1.499 + linksource = true;
1.500 + } else if (opt.equals("-sourcetab")) {
1.501 + linksource = true;
1.502 + try {
1.503 + setTabWidth(Integer.parseInt(os[1]));
1.504 + } catch (NumberFormatException e) {
1.505 + //Set to -1 so that warning will be printed
1.506 + //to indicate what is valid argument.
1.507 + sourcetab = -1;
1.508 + }
1.509 + if (sourcetab <= 0) {
1.510 + message.warning("doclet.sourcetab_warning");
1.511 + setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
1.512 + }
1.513 + } else if (opt.equals("-notimestamp")) {
1.514 + notimestamp = true;
1.515 + } else if (opt.equals("-nocomment")) {
1.516 + nocomment = true;
1.517 + } else if (opt.equals("-tag") || opt.equals("-taglet")) {
1.518 + customTagStrs.add(os);
1.519 + } else if (opt.equals("-tagletpath")) {
1.520 + tagletpath = os[1];
1.521 + } else if (opt.equals("-xprofilespath")) {
1.522 + profilespath = os[1];
1.523 + } else if (opt.equals("-keywords")) {
1.524 + keywords = true;
1.525 + } else if (opt.equals("-serialwarn")) {
1.526 + serialwarn = true;
1.527 + } else if (opt.equals("-group")) {
1.528 + group.checkPackageGroups(os[1], os[2]);
1.529 + } else if (opt.equals("-link")) {
1.530 + String url = os[1];
1.531 + extern.link(url, url, root, false);
1.532 + } else if (opt.equals("-linkoffline")) {
1.533 + String url = os[1];
1.534 + String pkglisturl = os[2];
1.535 + extern.link(url, pkglisturl, root, true);
1.536 + }
1.537 + }
1.538 + if (sourcepath.length() == 0) {
1.539 + sourcepath = System.getProperty("env.class.path") == null ? "" :
1.540 + System.getProperty("env.class.path");
1.541 + }
1.542 + if (docencoding == null) {
1.543 + docencoding = encoding;
1.544 + }
1.545 +
1.546 + classDocCatalog = new ClassDocCatalog(root.specifiedClasses(), this);
1.547 + initTagletManager(customTagStrs);
1.548 + }
1.549 +
1.550 + /**
1.551 + * Set the command line options supported by this configuration.
1.552 + *
1.553 + * @throws DocletAbortException
1.554 + */
1.555 + public void setOptions() throws Fault {
1.556 + initPackageArray();
1.557 + setOptions(root.options());
1.558 + try {
1.559 + initProfiles();
1.560 + } catch (Exception e) {
1.561 + throw new DocletAbortException(e);
1.562 + }
1.563 + setSpecificDocletOptions(root.options());
1.564 + }
1.565 +
1.566 + private void ensureOutputDirExists() throws Fault {
1.567 + DocFile destDir = DocFile.createFileForDirectory(this, destDirName);
1.568 + if (!destDir.exists()) {
1.569 + //Create the output directory (in case it doesn't exist yet)
1.570 + root.printNotice(getText("doclet.dest_dir_create", destDirName));
1.571 + destDir.mkdirs();
1.572 + } else if (!destDir.isDirectory()) {
1.573 + throw new Fault(getText(
1.574 + "doclet.destination_directory_not_directory_0",
1.575 + destDir.getPath()));
1.576 + } else if (!destDir.canWrite()) {
1.577 + throw new Fault(getText(
1.578 + "doclet.destination_directory_not_writable_0",
1.579 + destDir.getPath()));
1.580 + }
1.581 + }
1.582 +
1.583 +
1.584 + /**
1.585 + * Initialize the taglet manager. The strings to initialize the simple custom tags should
1.586 + * be in the following format: "[tag name]:[location str]:[heading]".
1.587 + * @param customTagStrs the set two dimensional arrays of strings. These arrays contain
1.588 + * either -tag or -taglet arguments.
1.589 + */
1.590 + private void initTagletManager(Set<String[]> customTagStrs) {
1.591 + tagletManager = tagletManager == null ?
1.592 + new TagletManager(nosince, showversion, showauthor, javafx, message) :
1.593 + tagletManager;
1.594 + String[] args;
1.595 + for (Iterator<String[]> it = customTagStrs.iterator(); it.hasNext(); ) {
1.596 + args = it.next();
1.597 + if (args[0].equals("-taglet")) {
1.598 + tagletManager.addCustomTag(args[1], getFileManager(), tagletpath);
1.599 + continue;
1.600 + }
1.601 + String[] tokens = tokenize(args[1],
1.602 + TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);
1.603 + if (tokens.length == 1) {
1.604 + String tagName = args[1];
1.605 + if (tagletManager.isKnownCustomTag(tagName)) {
1.606 + //reorder a standard tag
1.607 + tagletManager.addNewSimpleCustomTag(tagName, null, "");
1.608 + } else {
1.609 + //Create a simple tag with the heading that has the same name as the tag.
1.610 + StringBuilder heading = new StringBuilder(tagName + ":");
1.611 + heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
1.612 + tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
1.613 + }
1.614 + } else if (tokens.length == 2) {
1.615 + //Add simple taglet without heading, probably to excluding it in the output.
1.616 + tagletManager.addNewSimpleCustomTag(tokens[0], tokens[1], "");
1.617 + } else if (tokens.length >= 3) {
1.618 + tagletManager.addNewSimpleCustomTag(tokens[0], tokens[2], tokens[1]);
1.619 + } else {
1.620 + message.error("doclet.Error_invalid_custom_tag_argument", args[1]);
1.621 + }
1.622 + }
1.623 + }
1.624 +
1.625 + /**
1.626 + * Given a string, return an array of tokens. The separator can be escaped
1.627 + * with the '\' character. The '\' character may also be escaped by the
1.628 + * '\' character.
1.629 + *
1.630 + * @param s the string to tokenize.
1.631 + * @param separator the separator char.
1.632 + * @param maxTokens the maximum number of tokens returned. If the
1.633 + * max is reached, the remaining part of s is appended
1.634 + * to the end of the last token.
1.635 + *
1.636 + * @return an array of tokens.
1.637 + */
1.638 + private String[] tokenize(String s, char separator, int maxTokens) {
1.639 + List<String> tokens = new ArrayList<String>();
1.640 + StringBuilder token = new StringBuilder ();
1.641 + boolean prevIsEscapeChar = false;
1.642 + for (int i = 0; i < s.length(); i += Character.charCount(i)) {
1.643 + int currentChar = s.codePointAt(i);
1.644 + if (prevIsEscapeChar) {
1.645 + // Case 1: escaped character
1.646 + token.appendCodePoint(currentChar);
1.647 + prevIsEscapeChar = false;
1.648 + } else if (currentChar == separator && tokens.size() < maxTokens-1) {
1.649 + // Case 2: separator
1.650 + tokens.add(token.toString());
1.651 + token = new StringBuilder();
1.652 + } else if (currentChar == '\\') {
1.653 + // Case 3: escape character
1.654 + prevIsEscapeChar = true;
1.655 + } else {
1.656 + // Case 4: regular character
1.657 + token.appendCodePoint(currentChar);
1.658 + }
1.659 + }
1.660 + if (token.length() > 0) {
1.661 + tokens.add(token.toString());
1.662 + }
1.663 + return tokens.toArray(new String[] {});
1.664 + }
1.665 +
1.666 + private void addToSet(Set<String> s, String str){
1.667 + StringTokenizer st = new StringTokenizer(str, ":");
1.668 + String current;
1.669 + while(st.hasMoreTokens()){
1.670 + current = st.nextToken();
1.671 + s.add(current);
1.672 + }
1.673 + }
1.674 +
1.675 + /**
1.676 + * Add a trailing file separator, if not found. Remove superfluous
1.677 + * file separators if any. Preserve the front double file separator for
1.678 + * UNC paths.
1.679 + *
1.680 + * @param path Path under consideration.
1.681 + * @return String Properly constructed path string.
1.682 + */
1.683 + public static String addTrailingFileSep(String path) {
1.684 + String fs = System.getProperty("file.separator");
1.685 + String dblfs = fs + fs;
1.686 + int indexDblfs;
1.687 + while ((indexDblfs = path.indexOf(dblfs, 1)) >= 0) {
1.688 + path = path.substring(0, indexDblfs) +
1.689 + path.substring(indexDblfs + fs.length());
1.690 + }
1.691 + if (!path.endsWith(fs))
1.692 + path += fs;
1.693 + return path;
1.694 + }
1.695 +
1.696 + /**
1.697 + * This checks for the validity of the options used by the user.
1.698 + * This works exactly like
1.699 + * {@link com.sun.javadoc.Doclet#validOptions(String[][],
1.700 + * DocErrorReporter)}. This will validate the options which are shared
1.701 + * by our doclets. For example, this method will flag an error using
1.702 + * the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
1.703 + * together.
1.704 + *
1.705 + * @param options options used on the command line.
1.706 + * @param reporter used to report errors.
1.707 + * @return true if all the options are valid.
1.708 + */
1.709 + public boolean generalValidOptions(String options[][],
1.710 + DocErrorReporter reporter) {
1.711 + boolean docencodingfound = false;
1.712 + String encoding = "";
1.713 + for (int oi = 0; oi < options.length; oi++) {
1.714 + String[] os = options[oi];
1.715 + String opt = StringUtils.toLowerCase(os[0]);
1.716 + if (opt.equals("-docencoding")) {
1.717 + docencodingfound = true;
1.718 + if (!checkOutputFileEncoding(os[1], reporter)) {
1.719 + return false;
1.720 + }
1.721 + } else if (opt.equals("-encoding")) {
1.722 + encoding = os[1];
1.723 + }
1.724 + }
1.725 + if (!docencodingfound && encoding.length() > 0) {
1.726 + if (!checkOutputFileEncoding(encoding, reporter)) {
1.727 + return false;
1.728 + }
1.729 + }
1.730 + return true;
1.731 + }
1.732 +
1.733 + /**
1.734 + * Check the validity of the given profile. Return false if there are no
1.735 + * valid packages to be documented for the profile.
1.736 + *
1.737 + * @param profileName the profile that needs to be validated.
1.738 + * @return true if the profile has valid packages to be documented.
1.739 + */
1.740 + public boolean shouldDocumentProfile(String profileName) {
1.741 + return profilePackages.containsKey(profileName);
1.742 + }
1.743 +
1.744 + /**
1.745 + * Check the validity of the given Source or Output File encoding on this
1.746 + * platform.
1.747 + *
1.748 + * @param docencoding output file encoding.
1.749 + * @param reporter used to report errors.
1.750 + */
1.751 + private boolean checkOutputFileEncoding(String docencoding,
1.752 + DocErrorReporter reporter) {
1.753 + OutputStream ost= new ByteArrayOutputStream();
1.754 + OutputStreamWriter osw = null;
1.755 + try {
1.756 + osw = new OutputStreamWriter(ost, docencoding);
1.757 + } catch (UnsupportedEncodingException exc) {
1.758 + reporter.printError(getText("doclet.Encoding_not_supported",
1.759 + docencoding));
1.760 + return false;
1.761 + } finally {
1.762 + try {
1.763 + if (osw != null) {
1.764 + osw.close();
1.765 + }
1.766 + } catch (IOException exc) {
1.767 + }
1.768 + }
1.769 + return true;
1.770 + }
1.771 +
1.772 + /**
1.773 + * Return true if the given doc-file subdirectory should be excluded and
1.774 + * false otherwise.
1.775 + * @param docfilesubdir the doc-files subdirectory to check.
1.776 + */
1.777 + public boolean shouldExcludeDocFileDir(String docfilesubdir){
1.778 + if (excludedDocFileDirs.contains(docfilesubdir)) {
1.779 + return true;
1.780 + } else {
1.781 + return false;
1.782 + }
1.783 + }
1.784 +
1.785 + /**
1.786 + * Return true if the given qualifier should be excluded and false otherwise.
1.787 + * @param qualifier the qualifier to check.
1.788 + */
1.789 + public boolean shouldExcludeQualifier(String qualifier){
1.790 + if (excludedQualifiers.contains("all") ||
1.791 + excludedQualifiers.contains(qualifier) ||
1.792 + excludedQualifiers.contains(qualifier + ".*")) {
1.793 + return true;
1.794 + } else {
1.795 + int index = -1;
1.796 + while ((index = qualifier.indexOf(".", index + 1)) != -1) {
1.797 + if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {
1.798 + return true;
1.799 + }
1.800 + }
1.801 + return false;
1.802 + }
1.803 + }
1.804 +
1.805 + /**
1.806 + * Return the qualified name of the <code>ClassDoc</code> if it's qualifier is not excluded. Otherwise,
1.807 + * return the unqualified <code>ClassDoc</code> name.
1.808 + * @param cd the <code>ClassDoc</code> to check.
1.809 + */
1.810 + public String getClassName(ClassDoc cd) {
1.811 + PackageDoc pd = cd.containingPackage();
1.812 + if (pd != null && shouldExcludeQualifier(cd.containingPackage().name())) {
1.813 + return cd.name();
1.814 + } else {
1.815 + return cd.qualifiedName();
1.816 + }
1.817 + }
1.818 +
1.819 + public String getText(String key) {
1.820 + try {
1.821 + //Check the doclet specific properties file.
1.822 + return getDocletSpecificMsg().getText(key);
1.823 + } catch (Exception e) {
1.824 + //Check the shared properties file.
1.825 + return message.getText(key);
1.826 + }
1.827 + }
1.828 +
1.829 + public String getText(String key, String a1) {
1.830 + try {
1.831 + //Check the doclet specific properties file.
1.832 + return getDocletSpecificMsg().getText(key, a1);
1.833 + } catch (Exception e) {
1.834 + //Check the shared properties file.
1.835 + return message.getText(key, a1);
1.836 + }
1.837 + }
1.838 +
1.839 + public String getText(String key, String a1, String a2) {
1.840 + try {
1.841 + //Check the doclet specific properties file.
1.842 + return getDocletSpecificMsg().getText(key, a1, a2);
1.843 + } catch (Exception e) {
1.844 + //Check the shared properties file.
1.845 + return message.getText(key, a1, a2);
1.846 + }
1.847 + }
1.848 +
1.849 + public String getText(String key, String a1, String a2, String a3) {
1.850 + try {
1.851 + //Check the doclet specific properties file.
1.852 + return getDocletSpecificMsg().getText(key, a1, a2, a3);
1.853 + } catch (Exception e) {
1.854 + //Check the shared properties file.
1.855 + return message.getText(key, a1, a2, a3);
1.856 + }
1.857 + }
1.858 +
1.859 + public abstract Content newContent();
1.860 +
1.861 + /**
1.862 + * Get the configuration string as a content.
1.863 + *
1.864 + * @param key the key to look for in the configuration file
1.865 + * @return a content tree for the text
1.866 + */
1.867 + public Content getResource(String key) {
1.868 + Content c = newContent();
1.869 + c.addContent(getText(key));
1.870 + return c;
1.871 + }
1.872 +
1.873 + /**
1.874 + * Get the configuration string as a content.
1.875 + *
1.876 + * @param key the key to look for in the configuration file
1.877 + * @param o string or content argument added to configuration text
1.878 + * @return a content tree for the text
1.879 + */
1.880 + public Content getResource(String key, Object o) {
1.881 + return getResource(key, o, null, null);
1.882 + }
1.883 +
1.884 + /**
1.885 + * Get the configuration string as a content.
1.886 + *
1.887 + * @param key the key to look for in the configuration file
1.888 + * @param o string or content argument added to configuration text
1.889 + * @return a content tree for the text
1.890 + */
1.891 + public Content getResource(String key, Object o1, Object o2) {
1.892 + return getResource(key, o1, o2, null);
1.893 + }
1.894 +
1.895 + /**
1.896 + * Get the configuration string as a content.
1.897 + *
1.898 + * @param key the key to look for in the configuration file
1.899 + * @param o1 string or content argument added to configuration text
1.900 + * @param o2 string or content argument added to configuration text
1.901 + * @return a content tree for the text
1.902 + */
1.903 + public Content getResource(String key, Object o0, Object o1, Object o2) {
1.904 + Content c = newContent();
1.905 + Pattern p = Pattern.compile("\\{([012])\\}");
1.906 + String text = getText(key);
1.907 + Matcher m = p.matcher(text);
1.908 + int start = 0;
1.909 + while (m.find(start)) {
1.910 + c.addContent(text.substring(start, m.start()));
1.911 +
1.912 + Object o = null;
1.913 + switch (m.group(1).charAt(0)) {
1.914 + case '0': o = o0; break;
1.915 + case '1': o = o1; break;
1.916 + case '2': o = o2; break;
1.917 + }
1.918 +
1.919 + if (o == null) {
1.920 + c.addContent("{" + m.group(1) + "}");
1.921 + } else if (o instanceof String) {
1.922 + c.addContent((String) o);
1.923 + } else if (o instanceof Content) {
1.924 + c.addContent((Content) o);
1.925 + }
1.926 +
1.927 + start = m.end();
1.928 + }
1.929 +
1.930 + c.addContent(text.substring(start));
1.931 + return c;
1.932 + }
1.933 +
1.934 +
1.935 + /**
1.936 + * Return true if the ClassDoc element is getting documented, depending upon
1.937 + * -nodeprecated option and the deprecation information. Return true if
1.938 + * -nodeprecated is not used. Return false if -nodeprecated is used and if
1.939 + * either ClassDoc element is deprecated or the containing package is deprecated.
1.940 + *
1.941 + * @param cd the ClassDoc for which the page generation is checked
1.942 + */
1.943 + public boolean isGeneratedDoc(ClassDoc cd) {
1.944 + if (!nodeprecated) {
1.945 + return true;
1.946 + }
1.947 + return !(Util.isDeprecated(cd) || Util.isDeprecated(cd.containingPackage()));
1.948 + }
1.949 +
1.950 + /**
1.951 + * Return the doclet specific instance of a writer factory.
1.952 + * @return the {@link WriterFactory} for the doclet.
1.953 + */
1.954 + public abstract WriterFactory getWriterFactory();
1.955 +
1.956 + /**
1.957 + * Return the input stream to the builder XML.
1.958 + *
1.959 + * @return the input steam to the builder XML.
1.960 + * @throws FileNotFoundException when the given XML file cannot be found.
1.961 + */
1.962 + public InputStream getBuilderXML() throws IOException {
1.963 + return builderXMLPath == null ?
1.964 + Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :
1.965 + DocFile.createFileForInput(this, builderXMLPath).openInputStream();
1.966 + }
1.967 +
1.968 + /**
1.969 + * Return the Locale for this document.
1.970 + */
1.971 + public abstract Locale getLocale();
1.972 +
1.973 + /**
1.974 + * Return the current file manager.
1.975 + */
1.976 + public abstract JavaFileManager getFileManager();
1.977 +
1.978 + /**
1.979 + * Return the comparator that will be used to sort member documentation.
1.980 + * To no do any sorting, return null.
1.981 + *
1.982 + * @return the {@link java.util.Comparator} used to sort members.
1.983 + */
1.984 + public abstract Comparator<ProgramElementDoc> getMemberComparator();
1.985 +
1.986 + private void setTabWidth(int n) {
1.987 + sourcetab = n;
1.988 + tabSpaces = String.format("%" + n + "s", "");
1.989 + }
1.990 +
1.991 + public abstract boolean showMessage(SourcePosition pos, String key);
1.992 +}
