1 /*
   2  * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.javadoc.internal.doclets.toolkit;
  27 
  28 import java.io.*;
  29 import java.lang.ref.*;
  30 import java.util.*;
  31 
  32 import javax.lang.model.element.Element;
  33 import javax.lang.model.element.ModuleElement;
  34 import javax.lang.model.element.PackageElement;
  35 import javax.lang.model.element.TypeElement;
  36 import javax.lang.model.util.SimpleElementVisitor9;
  37 import javax.tools.JavaFileManager;
  38 import javax.tools.JavaFileObject;
  39 
  40 import com.sun.source.util.DocTreePath;
  41 import com.sun.tools.javac.util.DefinedBy;
  42 import com.sun.tools.javac.util.DefinedBy.Api;
  43 import jdk.javadoc.doclet.Doclet;
  44 import jdk.javadoc.doclet.DocletEnvironment;
  45 import jdk.javadoc.doclet.Reporter;
  46 import jdk.javadoc.doclet.StandardDoclet;
  47 import jdk.javadoc.doclet.Taglet;
  48 import jdk.javadoc.internal.doclets.formats.html.HtmlDoclet;
  49 import jdk.javadoc.internal.doclets.toolkit.builders.BuilderFactory;
  50 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager;
  51 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
  52 import jdk.javadoc.internal.doclets.toolkit.util.DocFileFactory;
  53 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  54 import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
  55 import jdk.javadoc.internal.doclets.toolkit.util.Extern;
  56 import jdk.javadoc.internal.doclets.toolkit.util.Group;
  57 import jdk.javadoc.internal.doclets.toolkit.util.MetaKeywords;
  58 import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException;
  59 import jdk.javadoc.internal.doclets.toolkit.util.TypeElementCatalog;
  60 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  61 import jdk.javadoc.internal.doclets.toolkit.util.Utils.Pair;
  62 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberCache;
  63 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
  64 
  65 import static javax.tools.Diagnostic.Kind.*;
  66 
  67 /**
  68  * Configure the output based on the options. Doclets should sub-class
  69  * BaseConfiguration, to configure and add their own options. This class contains
  70  * all user options which are supported by the standard doclet.
  71  * <p>
  72  * <p><b>This is NOT part of any supported API.
  73  * If you write code that depends on this, you do so at your own risk.
  74  * This code and its internal interfaces are subject to change or
  75  * deletion without notice.</b>
  76  *
  77  * @author Robert Field.
  78  * @author Atul Dambalkar.
  79  * @author Jamie Ho
  80  */
  81 public abstract class BaseConfiguration {
  82     /**
  83      * The doclet that created this configuration.
  84      */
  85     public final Doclet doclet;
  86 
  87     /**
  88      * The factory for builders.
  89      */
  90     protected BuilderFactory builderFactory;
  91 
  92     /**
  93      * The taglet manager.
  94      */
  95     public TagletManager tagletManager;
  96 
  97     /**
  98      * The path to the builder XML input file.
  99      */
 100     public String builderXMLPath;
 101 
 102     /**
 103      * The default path to the builder XML.
 104      */
 105     public static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";
 106 
 107     /**
 108      * The path to Taglets
 109      */
 110     public String tagletpath = null;
 111 
 112     /**
 113      * This is true if option "-serialwarn" is used. Defualt value is false to
 114      * suppress excessive warnings about serial tag.
 115      */
 116     public boolean serialwarn = false;
 117 
 118     /**
 119      * The specified amount of space between tab stops.
 120      */
 121     public int sourcetab;
 122 
 123     public String tabSpaces;
 124 
 125     /**
 126      * True if we should generate browsable sources.
 127      */
 128     public boolean linksource = false;
 129 
 130     /**
 131      * True if command line option "-nosince" is used. Default value is
 132      * false.
 133      */
 134     public boolean nosince = false;
 135 
 136     /**
 137      * True if we should recursively copy the doc-file subdirectories
 138      */
 139     public boolean copydocfilesubdirs = false;
 140 
 141     /**
 142      * Maintain backward compatibility with previous javadoc version
 143      */
 144     public boolean backwardCompatibility = true;
 145 
 146     /**
 147      * True if user wants to add member names as meta keywords.
 148      * Set to false because meta keywords are ignored in general
 149      * by most Internet search engines.
 150      */
 151     public boolean keywords = false;
 152 
 153     /**
 154      * The meta tag keywords instance.
 155      */
 156     public final MetaKeywords metakeywords;
 157 
 158     /**
 159      * The set of doc-file subdirectories to exclude
 160      */
 161     protected Set<String> excludedDocFileDirs;
 162 
 163     /**
 164      * The set of qualifiers to exclude
 165      */
 166     protected Set<String> excludedQualifiers;
 167 
 168     /**
 169      * The doclet environment.
 170      */
 171     public DocletEnvironment docEnv;
 172 
 173     /**
 174      * An utility class for commonly used helpers
 175      */
 176     public Utils utils;
 177 
 178     /**
 179      * All the temporary accessors to javac internals.
 180      */
 181     public WorkArounds workArounds;
 182 
 183     /**
 184      * Destination directory name, in which doclet will generate the entire
 185      * documentation. Default is current directory.
 186      */
 187     public String destDirName = "";
 188 
 189     /**
 190      * Destination directory name, in which doclet will copy the doc-files to.
 191      */
 192     public String docFileDestDirName = "";
 193 
 194     /**
 195      * Encoding for this document. Default is default encoding for this
 196      * platform.
 197      */
 198     public String docencoding = null;
 199 
 200     /**
 201      * True if user wants to suppress descriptions and tags.
 202      */
 203     public boolean nocomment = false;
 204 
 205     /**
 206      * Encoding for this document. Default is default encoding for this
 207      * platform.
 208      */
 209     public String encoding = null;
 210 
 211     /**
 212      * Generate author specific information for all the classes if @author
 213      * tag is used in the doc comment and if -author option is used.
 214      * <code>showauthor</code> is set to true if -author option is used.
 215      * Default is don't show author information.
 216      */
 217     public boolean showauthor = false;
 218 
 219     /**
 220      * Generate documentation for JavaFX getters and setters automatically
 221      * by copying it from the appropriate property definition.
 222      */
 223     public boolean javafx = false;
 224 
 225     /**
 226      * Generate version specific information for the all the classes
 227      * if @version tag is used in the doc comment and if -version option is
 228      * used. <code>showversion</code> is set to true if -version option is
 229      * used.Default is don't show version information.
 230      */
 231     public boolean showversion = false;
 232 
 233     /**
 234      * Allow JavaScript in doc comments.
 235      */
 236     private boolean allowScriptInComments = false;
 237 
 238     /**
 239      * Sourcepath from where to read the source files. Default is classpath.
 240      */
 241     public String sourcepath = "";
 242 
 243     /**
 244      * Generate modules documentation if more than one module is present.
 245      */
 246     public boolean showModules = false;
 247 
 248     /**
 249      * Don't generate deprecated API information at all, if -nodeprecated
 250      * option is used. <code>nodepracted</code> is set to true if
 251      * -nodeprecated option is used. Default is generate deprected API
 252      * information.
 253      */
 254     public boolean nodeprecated = false;
 255 
 256     /**
 257      * The catalog of classes specified on the command-line
 258      */
 259     public TypeElementCatalog typeElementCatalog;
 260 
 261     /**
 262      * True if user wants to suppress time stamp in output.
 263      * Default is false.
 264      */
 265     public boolean notimestamp = false;
 266 
 267     /**
 268      * The package grouping instance.
 269      */
 270     public final Group group = new Group(this);
 271 
 272     /**
 273      * The tracker of external package links.
 274      */
 275     public Extern extern;
 276 
 277     public Reporter reporter;
 278 
 279     public Locale locale;
 280 
 281     /**
 282      * Suppress all messages
 283      */
 284     public boolean quiet = false;
 285 
 286     /**
 287      * Specifies whether those methods that override a super-type's method
 288      * with no changes to the API contract should be summarized in the
 289      * footnote section.
 290      */
 291     public boolean summarizeOverriddenMethods = false;
 292 
 293     // A list containing urls
 294     private final List<String> linkList = new ArrayList<>();
 295 
 296      // A list of pairs containing urls and package list
 297     private final List<Pair<String, String>> linkOfflineList = new ArrayList<>();
 298 
 299     /**
 300      * Flag to enable/disable use of module directories when generating docs for modules
 301      * Default: on (module directories are enabled).
 302      */
 303     public boolean useModuleDirectories = true;
 304 
 305     public boolean dumpOnError = false;
 306 
 307     private List<Pair<String, String>> groupPairs;
 308 
 309     public abstract Messages getMessages();
 310 
 311     public abstract Resources getResources();
 312 
 313     /**
 314      * Returns a string identifying the version of the doclet.
 315      *
 316      * @return a version string
 317      */
 318     public abstract String getDocletVersion();
 319 
 320     /**
 321      * This method should be defined in all those doclets (configurations),
 322      * which want to derive themselves from this BaseConfiguration. This method
 323      * can be used to finish up the options setup.
 324      *
 325      * @return true if successful and false otherwise
 326      */
 327 
 328     public abstract boolean finishOptionSettings();
 329 
 330     public CommentUtils cmtUtils;
 331 
 332     /**
 333      * A sorted set of included packages.
 334      */
 335     public SortedSet<PackageElement> packages = null;
 336 
 337     public OverviewElement overviewElement;
 338 
 339     public DocFileFactory docFileFactory;
 340 
 341     /**
 342      * A sorted map, giving the (specified|included|other) packages for each module.
 343      */
 344     public SortedMap<ModuleElement, Set<PackageElement>> modulePackages;
 345 
 346     /**
 347      * The list of known modules, that should be documented.
 348      */
 349     public SortedSet<ModuleElement> modules;
 350 
 351     protected static final String sharedResourceBundleName =
 352             "jdk.javadoc.internal.doclets.toolkit.resources.doclets";
 353 
 354     /**
 355      * Primarily used to disable strict checks in the regression
 356      * tests allowing those tests to be executed successfully, for
 357      * instance, with OpenJDK builds which may not contain FX libraries.
 358      */
 359     public boolean disableJavaFxStrictChecks = false;
 360 
 361     /**
 362      * Show taglets (internal debug switch)
 363      */
 364     public boolean showTaglets = false;
 365 
 366     VisibleMemberCache visibleMemberCache = null;
 367 
 368     public PropertyUtils propertyUtils = null;
 369 
 370     /**
 371      * Constructs the configurations needed by the doclet.
 372      *
 373      * @apiNote
 374      * The {@code doclet} parameter is used when {@link Taglet#init(DocletEnvironment, Doclet)
 375      * initializing tags}.
 376      * Some doclets (such as the {@link StandardDoclet), may delegate to another
 377      * (such as the {@link HtmlDoclet}).  In such cases, the primary doclet (i.e
 378      * {@code StandardDoclet}) should be provided here, and not any internal
 379      * class like {@code HtmlDoclet}.
 380      *
 381      * @param doclet the doclet for this run of javadoc
 382      */
 383     public BaseConfiguration(Doclet doclet) {
 384         this.doclet = doclet;
 385         excludedDocFileDirs = new HashSet<>();
 386         excludedQualifiers = new HashSet<>();
 387         setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
 388         metakeywords = new MetaKeywords(this);
 389         groupPairs = new ArrayList<>(0);
 390     }
 391 
 392     private boolean initialized = false;
 393 
 394     protected void initConfiguration(DocletEnvironment docEnv) {
 395         if (initialized) {
 396             throw new IllegalStateException("configuration previously initialized");
 397         }
 398         initialized = true;
 399         this.docEnv = docEnv;
 400         // Utils needs docEnv, safe to init now.
 401         utils = new Utils(this);
 402 
 403         if (!javafx) {
 404             javafx = isJavaFXMode();
 405         }
 406 
 407         // Once docEnv and Utils have been initialized, others should be safe.
 408         cmtUtils = new CommentUtils(this);
 409         workArounds = new WorkArounds(this);
 410         visibleMemberCache = new VisibleMemberCache(this);
 411         propertyUtils = new PropertyUtils(this);
 412 
 413         Splitter specifiedSplitter = new Splitter(docEnv, false);
 414         specifiedModuleElements = Collections.unmodifiableSet(specifiedSplitter.mset);
 415         specifiedPackageElements = Collections.unmodifiableSet(specifiedSplitter.pset);
 416         specifiedTypeElements = Collections.unmodifiableSet(specifiedSplitter.tset);
 417 
 418         Splitter includedSplitter = new Splitter(docEnv, true);
 419         includedModuleElements = Collections.unmodifiableSet(includedSplitter.mset);
 420         includedPackageElements = Collections.unmodifiableSet(includedSplitter.pset);
 421         includedTypeElements = Collections.unmodifiableSet(includedSplitter.tset);
 422     }
 423 
 424     /**
 425      * Return the builder factory for this doclet.
 426      *
 427      * @return the builder factory for this doclet.
 428      */
 429     public BuilderFactory getBuilderFactory() {
 430         if (builderFactory == null) {
 431             builderFactory = new BuilderFactory(this);
 432         }
 433         return builderFactory;
 434     }
 435 
 436     public Reporter getReporter() {
 437         return this.reporter;
 438     }
 439 
 440     private Set<ModuleElement> specifiedModuleElements;
 441 
 442     public Set<ModuleElement> getSpecifiedModuleElements() {
 443         return specifiedModuleElements;
 444     }
 445 
 446     private Set<PackageElement> specifiedPackageElements;
 447 
 448     public Set<PackageElement> getSpecifiedPackageElements() {
 449         return specifiedPackageElements;
 450     }
 451 
 452     private Set<TypeElement> specifiedTypeElements;
 453 
 454     public Set<TypeElement> getSpecifiedTypeElements() {
 455         return specifiedTypeElements;
 456     }
 457 
 458     private Set<ModuleElement> includedModuleElements;
 459 
 460     public Set<ModuleElement> getIncludedModuleElements() {
 461         return includedModuleElements;
 462     }
 463 
 464     private Set<PackageElement> includedPackageElements;
 465 
 466     public Set<PackageElement> getIncludedPackageElements() {
 467         return includedPackageElements;
 468     }
 469 
 470     private Set<TypeElement> includedTypeElements;
 471 
 472     public Set<TypeElement> getIncludedTypeElements() {
 473         return includedTypeElements;
 474     }
 475 
 476     private void initModules() {
 477         // Build the modules structure used by the doclet
 478         modules = new TreeSet<>(utils.makeModuleComparator());
 479         modules.addAll(getSpecifiedModuleElements());
 480 
 481         modulePackages = new TreeMap<>(utils.makeModuleComparator());
 482         for (PackageElement p : packages) {
 483             ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);
 484             if (mdle != null && !mdle.isUnnamed()) {
 485                 Set<PackageElement> s = modulePackages
 486                         .computeIfAbsent(mdle, m -> new TreeSet<>(utils.makePackageComparator()));
 487                 s.add(p);
 488             }
 489         }
 490 
 491         for (PackageElement p : getIncludedPackageElements()) {
 492             ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);
 493             if (mdle != null && !mdle.isUnnamed()) {
 494                 Set<PackageElement> s = modulePackages
 495                         .computeIfAbsent(mdle, m -> new TreeSet<>(utils.makePackageComparator()));
 496                 s.add(p);
 497             }
 498         }
 499 
 500         // add entries for modules which may not have exported packages
 501         modules.forEach((ModuleElement mdle) -> {
 502             modulePackages.computeIfAbsent(mdle, m -> Collections.emptySet());
 503         });
 504 
 505         modules.addAll(modulePackages.keySet());
 506         showModules = !modules.isEmpty();
 507         for (Set<PackageElement> pkgs : modulePackages.values()) {
 508             packages.addAll(pkgs);
 509         }
 510     }
 511 
 512     private void initPackages() {
 513         packages = new TreeSet<>(utils.makePackageComparator());
 514         // add all the included packages
 515         packages.addAll(includedPackageElements);
 516     }
 517 
 518     public Set<Doclet.Option> getSupportedOptions() {
 519         Resources resources = getResources();
 520         Doclet.Option[] options = {
 521                 new Option(resources, "-author") {
 522                     @Override
 523                     public boolean process(String opt, List<String> args) {
 524                         showauthor = true;
 525                         return true;
 526                     }
 527                 },
 528                 new Option(resources, "-d", 1) {
 529                     @Override
 530                     public boolean process(String opt, List<String> args) {
 531                         destDirName = addTrailingFileSep(args.get(0));
 532                         return true;
 533                     }
 534                 },
 535                 new Option(resources, "-docencoding", 1) {
 536                     @Override
 537                     public boolean process(String opt, List<String> args) {
 538                         docencoding = args.get(0);
 539                         return true;
 540                     }
 541                 },
 542                 new Option(resources, "-docfilessubdirs") {
 543                     @Override
 544                     public boolean process(String opt, List<String> args) {
 545                         copydocfilesubdirs = true;
 546                         return true;
 547                     }
 548                 },
 549                 new Hidden(resources, "-encoding", 1) {
 550                     @Override
 551                     public boolean process(String opt, List<String> args) {
 552                         encoding = args.get(0);
 553                         return true;
 554                     }
 555                 },
 556                 new Option(resources, "-excludedocfilessubdir", 1) {
 557                     @Override
 558                     public boolean process(String opt, List<String> args) {
 559                         addToSet(excludedDocFileDirs, args.get(0));
 560                         return true;
 561                     }
 562                 },
 563                 new Option(resources, "-group", 2) {
 564                     @Override
 565                     public boolean process(String opt, List<String> args) {
 566                         groupPairs.add(new Pair<>(args.get(0), args.get(1)));
 567                         return true;
 568                     }
 569                 },
 570                 new Option(resources, "--javafx -javafx") {
 571                     @Override
 572                     public boolean process(String opt, List<String> args) {
 573                         javafx = true;
 574                         return true;
 575                     }
 576                 },
 577                 new Option(resources, "-keywords") {
 578                     @Override
 579                     public boolean process(String opt, List<String> args) {
 580                         keywords = true;
 581                         return true;
 582                     }
 583                 },
 584                 new Option(resources, "-link", 1) {
 585                     @Override
 586                     public boolean process(String opt, List<String> args) {
 587                         linkList.add(args.get(0));
 588                         return true;
 589                     }
 590                 },
 591                 new Option(resources, "-linksource") {
 592                     @Override
 593                     public boolean process(String opt, List<String> args) {
 594                         linksource = true;
 595                         return true;
 596                     }
 597                 },
 598                 new Option(resources, "-linkoffline", 2) {
 599                     @Override
 600                     public boolean process(String opt, List<String> args) {
 601                         linkOfflineList.add(new Pair<>(args.get(0), args.get(1)));
 602                         return true;
 603                     }
 604                 },
 605                 new Option(resources, "-nocomment") {
 606                     @Override
 607                     public boolean process(String opt, List<String> args) {
 608                         nocomment = true;
 609                         return true;
 610                     }
 611                 },
 612                 new Option(resources, "-nodeprecated") {
 613                     @Override
 614                     public boolean process(String opt, List<String> args) {
 615                         nodeprecated = true;
 616                         return true;
 617                     }
 618                 },
 619                 new Option(resources, "-nosince") {
 620                     @Override
 621                     public boolean process(String opt, List<String> args) {
 622                         nosince = true;
 623                         return true;
 624                     }
 625                 },
 626                 new Option(resources, "-notimestamp") {
 627                     @Override
 628                     public boolean process(String opt, List<String> args) {
 629                         notimestamp = true;
 630                         return true;
 631                     }
 632                 },
 633                 new Option(resources, "-noqualifier", 1) {
 634                     @Override
 635                     public boolean process(String opt, List<String> args) {
 636                         addToSet(excludedQualifiers, args.get(0));
 637                         return true;
 638                     }
 639                 },
 640                 new Option(resources, "--override-methods", 1) {
 641                     @Override
 642                     public boolean process(String opt,  List<String> args) {
 643                         String o = args.get(0);
 644                         switch (o) {
 645                             case "summary":
 646                                 summarizeOverriddenMethods = true;
 647                                 break;
 648                             case "detail":
 649                                 summarizeOverriddenMethods = false;
 650                                 break;
 651                             default:
 652                                 reporter.print(ERROR,
 653                                         getResources().getText("doclet.Option_invalid",o, "--override-methods"));
 654                                 return false;
 655                         }
 656                         return true;
 657                     }
 658                 },
 659                 new Hidden(resources, "-quiet") {
 660                     @Override
 661                     public boolean process(String opt, List<String> args) {
 662                         quiet = true;
 663                         return true;
 664                     }
 665                 },
 666                 new Option(resources, "-serialwarn") {
 667                     @Override
 668                     public boolean process(String opt, List<String> args) {
 669                         serialwarn = true;
 670                         return true;
 671                     }
 672                 },
 673                 new Option(resources, "-sourcetab", 1) {
 674                     @Override
 675                     public boolean process(String opt, List<String> args) {
 676                         linksource = true;
 677                         try {
 678                             setTabWidth(Integer.parseInt(args.get(0)));
 679                         } catch (NumberFormatException e) {
 680                             //Set to -1 so that warning will be printed
 681                             //to indicate what is valid argument.
 682                             sourcetab = -1;
 683                         }
 684                         if (sourcetab <= 0) {
 685                             getMessages().warning("doclet.sourcetab_warning");
 686                             setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
 687                         }
 688                         return true;
 689                     }
 690                 },
 691                 new Option(resources, "-tag", 1) {
 692                     @Override
 693                     public boolean process(String opt, List<String> args) {
 694                         ArrayList<String> list = new ArrayList<>();
 695                         list.add(opt);
 696                         list.add(args.get(0));
 697                         customTagStrs.add(list);
 698                         return true;
 699                     }
 700                 },
 701                 new Option(resources, "-taglet", 1) {
 702                     @Override
 703                     public boolean process(String opt, List<String> args) {
 704                         ArrayList<String> list = new ArrayList<>();
 705                         list.add(opt);
 706                         list.add(args.get(0));
 707                         customTagStrs.add(list);
 708                         return true;
 709                     }
 710                 },
 711                 new Option(resources, "-tagletpath", 1) {
 712                     @Override
 713                     public boolean process(String opt, List<String> args) {
 714                         tagletpath = args.get(0);
 715                         return true;
 716                     }
 717                 },
 718                 new Option(resources, "-version") {
 719                     @Override
 720                     public boolean process(String opt, List<String> args) {
 721                         showversion = true;
 722                         return true;
 723                     }
 724                 },
 725                 new Hidden(resources, "--dump-on-error") {
 726                     @Override
 727                     public boolean process(String opt, List<String> args) {
 728                         dumpOnError = true;
 729                         return true;
 730                     }
 731                 },
 732                 new Option(resources, "--allow-script-in-comments") {
 733                     @Override
 734                     public boolean process(String opt, List<String> args) {
 735                         allowScriptInComments = true;
 736                         return true;
 737                     }
 738                 },
 739                 new Hidden(resources, "--disable-javafx-strict-checks") {
 740                     @Override
 741                     public boolean process(String opt, List<String> args) {
 742                         disableJavaFxStrictChecks = true;
 743                         return true;
 744                     }
 745                 },
 746                 new Hidden(resources, "--show-taglets") {
 747                     @Override
 748                     public boolean process(String opt, List<String> args) {
 749                         showTaglets = true;
 750                         return true;
 751                     }
 752                 },
 753                 new XOption(resources, "--no-module-directories") {
 754                     @Override
 755                     public boolean process(String option, List<String> args) {
 756                         useModuleDirectories = false;
 757                         return true;
 758                     }
 759                 }
 760         };
 761         Set<Doclet.Option> set = new TreeSet<>();
 762         set.addAll(Arrays.asList(options));
 763         return set;
 764     }
 765 
 766     final LinkedHashSet<List<String>> customTagStrs = new LinkedHashSet<>();
 767 
 768     /*
 769      * when this is called all the option have been set, this method,
 770      * initializes certain components before anything else is started.
 771      */
 772     protected boolean finishOptionSettings0() throws DocletException {
 773         extern = new Extern(this);
 774         initDestDirectory();
 775         for (String link : linkList) {
 776             extern.link(link, reporter);
 777         }
 778         for (Pair<String, String> linkOfflinePair : linkOfflineList) {
 779             extern.link(linkOfflinePair.first, linkOfflinePair.second, reporter);
 780         }
 781         typeElementCatalog = new TypeElementCatalog(includedTypeElements, this);
 782         initTagletManager(customTagStrs);
 783         groupPairs.stream().forEach((grp) -> {
 784             if (showModules) {
 785                 group.checkModuleGroups(grp.first, grp.second);
 786             } else {
 787                 group.checkPackageGroups(grp.first, grp.second);
 788             }
 789         });
 790         overviewElement = new OverviewElement(workArounds.getUnnamedPackage(), getOverviewPath());
 791         return true;
 792     }
 793 
 794     /**
 795      * Set the command line options supported by this configuration.
 796      *
 797      * @return true if the options are set successfully
 798      * @throws DocletException if there is a problem while setting the options
 799      */
 800     public boolean setOptions() throws DocletException {
 801         initPackages();
 802         initModules();
 803         if (!finishOptionSettings0() || !finishOptionSettings())
 804             return false;
 805 
 806         return true;
 807     }
 808 
 809     private void initDestDirectory() throws DocletException {
 810         if (!destDirName.isEmpty()) {
 811             Resources resources = getResources();
 812             DocFile destDir = DocFile.createFileForDirectory(this, destDirName);
 813             if (!destDir.exists()) {
 814                 //Create the output directory (in case it doesn't exist yet)
 815                 reporter.print(NOTE, resources.getText("doclet.dest_dir_create", destDirName));
 816                 destDir.mkdirs();
 817             } else if (!destDir.isDirectory()) {
 818                 throw new SimpleDocletException(resources.getText(
 819                         "doclet.destination_directory_not_directory_0",
 820                         destDir.getPath()));
 821             } else if (!destDir.canWrite()) {
 822                 throw new SimpleDocletException(resources.getText(
 823                         "doclet.destination_directory_not_writable_0",
 824                         destDir.getPath()));
 825             }
 826         }
 827         DocFileFactory.getFactory(this).setDestDir(destDirName);
 828     }
 829 
 830     /**
 831      * Initialize the taglet manager.  The strings to initialize the simple custom tags should
 832      * be in the following format:  "[tag name]:[location str]:[heading]".
 833      *
 834      * @param customTagStrs the set two dimensional arrays of strings.  These arrays contain
 835      *                      either -tag or -taglet arguments.
 836      */
 837     private void initTagletManager(Set<List<String>> customTagStrs) {
 838         tagletManager = tagletManager == null ?
 839                 new TagletManager(nosince, showversion, showauthor, javafx, this) :
 840                 tagletManager;
 841         for (List<String> args : customTagStrs) {
 842             if (args.get(0).equals("-taglet")) {
 843                 tagletManager.addCustomTag(args.get(1), getFileManager(), tagletpath);
 844                 continue;
 845             }
 846             List<String> tokens = tokenize(args.get(1), TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);
 847             switch (tokens.size()) {
 848                 case 1:
 849                     String tagName = args.get(1);
 850                     if (tagletManager.isKnownCustomTag(tagName)) {
 851                         //reorder a standard tag
 852                         tagletManager.addNewSimpleCustomTag(tagName, null, "");
 853                     } else {
 854                         //Create a simple tag with the heading that has the same name as the tag.
 855                         StringBuilder heading = new StringBuilder(tagName + ":");
 856                         heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
 857                         tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
 858                     }
 859                     break;
 860 
 861                 case 2:
 862                     //Add simple taglet without heading, probably to excluding it in the output.
 863                     tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(1), "");
 864                     break;
 865 
 866                 case 3:
 867                     tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(2), tokens.get(1));
 868                     break;
 869 
 870                 default:
 871                     Messages messages = getMessages();
 872                     messages.error("doclet.Error_invalid_custom_tag_argument", args.get(1));
 873             }
 874         }
 875     }
 876 
 877     /**
 878      * Given a string, return an array of tokens.  The separator can be escaped
 879      * with the '\' character.  The '\' character may also be escaped by the
 880      * '\' character.
 881      *
 882      * @param s         the string to tokenize.
 883      * @param separator the separator char.
 884      * @param maxTokens the maximum number of tokens returned.  If the
 885      *                  max is reached, the remaining part of s is appended
 886      *                  to the end of the last token.
 887      * @return an array of tokens.
 888      */
 889     private List<String> tokenize(String s, char separator, int maxTokens) {
 890         List<String> tokens = new ArrayList<>();
 891         StringBuilder token = new StringBuilder();
 892         boolean prevIsEscapeChar = false;
 893         for (int i = 0; i < s.length(); i += Character.charCount(i)) {
 894             int currentChar = s.codePointAt(i);
 895             if (prevIsEscapeChar) {
 896                 // Case 1:  escaped character
 897                 token.appendCodePoint(currentChar);
 898                 prevIsEscapeChar = false;
 899             } else if (currentChar == separator && tokens.size() < maxTokens - 1) {
 900                 // Case 2:  separator
 901                 tokens.add(token.toString());
 902                 token = new StringBuilder();
 903             } else if (currentChar == '\\') {
 904                 // Case 3:  escape character
 905                 prevIsEscapeChar = true;
 906             } else {
 907                 // Case 4:  regular character
 908                 token.appendCodePoint(currentChar);
 909             }
 910         }
 911         if (token.length() > 0) {
 912             tokens.add(token.toString());
 913         }
 914         return tokens;
 915     }
 916 
 917     private void addToSet(Set<String> s, String str) {
 918         StringTokenizer st = new StringTokenizer(str, ":");
 919         String current;
 920         while (st.hasMoreTokens()) {
 921             current = st.nextToken();
 922             s.add(current);
 923         }
 924     }
 925 
 926     /**
 927      * Add a trailing file separator, if not found. Remove superfluous
 928      * file separators if any. Preserve the front double file separator for
 929      * UNC paths.
 930      *
 931      * @param path Path under consideration.
 932      * @return String Properly constructed path string.
 933      */
 934     public static String addTrailingFileSep(String path) {
 935         String fs = System.getProperty("file.separator");
 936         String dblfs = fs + fs;
 937         int indexDblfs;
 938         while ((indexDblfs = path.indexOf(dblfs, 1)) >= 0) {
 939             path = path.substring(0, indexDblfs) +
 940                     path.substring(indexDblfs + fs.length());
 941         }
 942         if (!path.endsWith(fs))
 943             path += fs;
 944         return path;
 945     }
 946 
 947     /**
 948      * This checks for the validity of the options used by the user.
 949      * As of this writing, this checks only docencoding.
 950      *
 951      * @return true if all the options are valid.
 952      */
 953     public boolean generalValidOptions() {
 954         if (docencoding != null) {
 955             if (!checkOutputFileEncoding(docencoding)) {
 956                 return false;
 957             }
 958         }
 959         if (docencoding == null && (encoding != null && !encoding.isEmpty())) {
 960             if (!checkOutputFileEncoding(encoding)) {
 961                 return false;
 962             }
 963         }
 964         return true;
 965     }
 966 
 967     /**
 968      * Check the validity of the given Source or Output File encoding on this
 969      * platform.
 970      *
 971      * @param docencoding output file encoding.
 972      */
 973     private boolean checkOutputFileEncoding(String docencoding) {
 974         OutputStream ost = new ByteArrayOutputStream();
 975         OutputStreamWriter osw = null;
 976         try {
 977             osw = new OutputStreamWriter(ost, docencoding);
 978         } catch (UnsupportedEncodingException exc) {
 979             reporter.print(ERROR, getResources().getText("doclet.Encoding_not_supported", docencoding));
 980             return false;
 981         } finally {
 982             try {
 983                 if (osw != null) {
 984                     osw.close();
 985                 }
 986             } catch (IOException exc) {
 987             }
 988         }
 989         return true;
 990     }
 991 
 992     /**
 993      * Return true if the given doc-file subdirectory should be excluded and
 994      * false otherwise.
 995      *
 996      * @param docfilesubdir the doc-files subdirectory to check.
 997      * @return true if the directory is excluded.
 998      */
 999     public boolean shouldExcludeDocFileDir(String docfilesubdir) {
1000         return excludedDocFileDirs.contains(docfilesubdir);
1001     }
1002 
1003     /**
1004      * Return true if the given qualifier should be excluded and false otherwise.
1005      *
1006      * @param qualifier the qualifier to check.
1007      * @return true if the qualifier should be excluded
1008      */
1009     public boolean shouldExcludeQualifier(String qualifier) {
1010         if (excludedQualifiers.contains("all") ||
1011                 excludedQualifiers.contains(qualifier) ||
1012                 excludedQualifiers.contains(qualifier + ".*")) {
1013             return true;
1014         } else {
1015             int index = -1;
1016             while ((index = qualifier.indexOf(".", index + 1)) != -1) {
1017                 if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {
1018                     return true;
1019                 }
1020             }
1021             return false;
1022         }
1023     }
1024 
1025     /**
1026      * Return the qualified name of the Element if its qualifier is not excluded.
1027      * Otherwise return the unqualified Element name.
1028      *
1029      * @param te the TypeElement to check.
1030      * @return the class name
1031      */
1032     public String getClassName(TypeElement te) {
1033         PackageElement pkg = utils.containingPackage(te);
1034         return shouldExcludeQualifier(utils.getPackageName(pkg))
1035                 ? utils.getSimpleName(te)
1036                 : utils.getFullyQualifiedName(te);
1037     }
1038 
1039     /**
1040      * Return true if the TypeElement element is getting documented, depending upon
1041      * -nodeprecated option and the deprecation information. Return true if
1042      * -nodeprecated is not used. Return false if -nodeprecated is used and if
1043      * either TypeElement element is deprecated or the containing package is deprecated.
1044      *
1045      * @param te the TypeElement for which the page generation is checked
1046      * @return true if it is a generated doc.
1047      */
1048     public boolean isGeneratedDoc(TypeElement te) {
1049         if (!nodeprecated) {
1050             return true;
1051         }
1052         return !(utils.isDeprecated(te) || utils.isDeprecated(utils.containingPackage(te)));
1053     }
1054 
1055     /**
1056      * Return the doclet specific instance of a writer factory.
1057      *
1058      * @return the {@link WriterFactory} for the doclet.
1059      */
1060     public abstract WriterFactory getWriterFactory();
1061 
1062     /**
1063      * Return the input stream to the builder XML.
1064      *
1065      * @return the input steam to the builder XML.
1066      * @throws DocFileIOException when the given XML file cannot be found or opened.
1067      */
1068     public InputStream getBuilderXML() throws DocFileIOException {
1069         return builderXMLPath == null ?
1070                 BaseConfiguration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :
1071                 DocFile.createFileForInput(this, builderXMLPath).openInputStream();
1072     }
1073 
1074     /**
1075      * Return the Locale for this document.
1076      *
1077      * @return the current locale
1078      */
1079     public abstract Locale getLocale();
1080 
1081     /**
1082      * Return the path of the overview file and null if it does not exist.
1083      *
1084      * @return the path of the overview file.
1085      */
1086     public abstract JavaFileObject getOverviewPath();
1087 
1088     /**
1089      * Return the current file manager.
1090      *
1091      * @return JavaFileManager
1092      */
1093     public abstract JavaFileManager getFileManager();
1094 
1095     private void setTabWidth(int n) {
1096         sourcetab = n;
1097         tabSpaces = String.format("%" + n + "s", "");
1098     }
1099 
1100     public abstract boolean showMessage(DocTreePath path, String key);
1101 
1102     public abstract boolean showMessage(Element e, String key);
1103 
1104     public static abstract class Option implements Doclet.Option, Comparable<Option> {
1105         private final String[] names;
1106         private final String parameters;
1107         private final String description;
1108         private final int argCount;
1109 
1110         protected Option(Resources resources, String name, int argCount) {
1111             this(resources, null, name, argCount);
1112         }
1113 
1114         protected Option(Resources resources, String keyBase, String name, int argCount) {
1115             this.names = name.trim().split("\\s+");
1116             if (keyBase == null) {
1117                 keyBase = "doclet.usage." + names[0].toLowerCase().replaceAll("^-+", "");
1118             }
1119             String desc = getOptionsMessage(resources, keyBase + ".description");
1120             if (desc.isEmpty()) {
1121                 this.description = "<MISSING KEY>";
1122                 this.parameters = "<MISSING KEY>";
1123             } else {
1124                 this.description = desc;
1125                 this.parameters = getOptionsMessage(resources, keyBase + ".parameters");
1126             }
1127             this.argCount = argCount;
1128         }
1129 
1130         protected Option(Resources resources, String name) {
1131             this(resources, name, 0);
1132         }
1133 
1134         private String getOptionsMessage(Resources resources, String key) {
1135             try {
1136                 return resources.getText(key);
1137             } catch (MissingResourceException ignore) {
1138                 return "";
1139             }
1140         }
1141 
1142         @Override
1143         public String getDescription() {
1144             return description;
1145         }
1146 
1147         @Override
1148         public Option.Kind getKind() {
1149             return Doclet.Option.Kind.STANDARD;
1150         }
1151 
1152         @Override
1153         public List<String> getNames() {
1154             return Arrays.asList(names);
1155         }
1156 
1157         @Override
1158         public String getParameters() {
1159             return parameters;
1160         }
1161 
1162         @Override
1163         public String toString() {
1164             return Arrays.toString(names);
1165         }
1166 
1167         @Override
1168         public int getArgumentCount() {
1169             return argCount;
1170         }
1171 
1172         public boolean matches(String option) {
1173             for (String name : names) {
1174                 boolean matchCase = name.startsWith("--");
1175                 if (option.startsWith("--") && option.contains("=")) {
1176                     return name.equals(option.substring(option.indexOf("=") + 1));
1177                 } else if (matchCase) {
1178                     return name.equals(option);
1179                 }
1180                 return name.toLowerCase().equals(option.toLowerCase());
1181             }
1182             return false;
1183         }
1184 
1185         @Override
1186         public int compareTo(Option that) {
1187             return this.getNames().get(0).compareTo(that.getNames().get(0));
1188         }
1189     }
1190 
1191     public abstract class XOption extends Option {
1192 
1193         public XOption(Resources resources, String prefix, String name, int argCount) {
1194             super(resources, prefix, name, argCount);
1195         }
1196 
1197         public XOption(Resources resources, String name, int argCount) {
1198             super(resources, name, argCount);
1199         }
1200 
1201         public XOption(Resources resources, String name) {
1202             this(resources, name, 0);
1203         }
1204 
1205         @Override
1206         public Option.Kind getKind() {
1207             return Doclet.Option.Kind.EXTENDED;
1208         }
1209     }
1210 
1211     public abstract class Hidden extends Option {
1212 
1213         public Hidden(Resources resources, String name, int argCount) {
1214             super(resources, name, argCount);
1215         }
1216 
1217         public Hidden(Resources resources, String name) {
1218             this(resources, name, 0);
1219         }
1220 
1221         @Override
1222         public Option.Kind getKind() {
1223             return Doclet.Option.Kind.OTHER;
1224         }
1225     }
1226 
1227     /*
1228      * Splits the elements in a collection to its individual
1229      * collection.
1230      */
1231     static private class Splitter {
1232 
1233         final Set<ModuleElement> mset = new LinkedHashSet<>();
1234         final Set<PackageElement> pset = new LinkedHashSet<>();
1235         final Set<TypeElement> tset = new LinkedHashSet<>();
1236 
1237         Splitter(DocletEnvironment docEnv, boolean included) {
1238 
1239             Set<? extends Element> inset = included
1240                     ? docEnv.getIncludedElements()
1241                     : docEnv.getSpecifiedElements();
1242 
1243             for (Element e : inset) {
1244                 new SimpleElementVisitor9<Void, Void>() {
1245                     @Override
1246                     @DefinedBy(Api.LANGUAGE_MODEL)
1247                     public Void visitModule(ModuleElement e, Void p) {
1248                         mset.add(e);
1249                         return null;
1250                     }
1251 
1252                     @Override
1253                     @DefinedBy(Api.LANGUAGE_MODEL)
1254                     public Void visitPackage(PackageElement e, Void p) {
1255                         pset.add(e);
1256                         return null;
1257                     }
1258 
1259                     @Override
1260                     @DefinedBy(Api.LANGUAGE_MODEL)
1261                     public Void visitType(TypeElement e, Void p) {
1262                         tset.add(e);
1263                         return null;
1264                     }
1265 
1266                     @Override
1267                     @DefinedBy(Api.LANGUAGE_MODEL)
1268                     protected Void defaultAction(Element e, Void p) {
1269                         throw new AssertionError("unexpected element: " + e);
1270                     }
1271 
1272                 }.visit(e);
1273             }
1274         }
1275     }
1276 
1277     /**
1278      * Returns whether or not to allow JavaScript in comments.
1279      * Default is off; can be set true from a command line option.
1280      *
1281      * @return the allowScriptInComments
1282      */
1283     public boolean isAllowScriptInComments() {
1284         return allowScriptInComments;
1285     }
1286 
1287     public synchronized VisibleMemberTable getVisibleMemberTable(TypeElement te) {
1288         return visibleMemberCache.getVisibleMemberTable(te);
1289     }
1290 
1291     /**
1292      * Determines if JavaFX is available in the compilation environment.
1293      * @return true if JavaFX is available
1294      */
1295     public boolean isJavaFXMode() {
1296         TypeElement observable = utils.elementUtils.getTypeElement("javafx.beans.Observable");
1297         if (observable != null) {
1298             ModuleElement javafxModule = utils.elementUtils.getModuleOf(observable);
1299             if (javafxModule == null || javafxModule.isUnnamed() || javafxModule.getQualifiedName().contentEquals("javafx.base")) {
1300                 return true;
1301             }
1302         }
1303         return false;
1304     }
1305 }