/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
package org.apache.tools.ant.taskdefs;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.MalformedURLException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Enumeration;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.StringTokenizer;
import java.util.Vector;
import java.util.stream.Collectors;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.DirectoryScanner;
import org.apache.tools.ant.MagicNames;
import org.apache.tools.ant.Project;
import org.apache.tools.ant.ProjectComponent;
import org.apache.tools.ant.Task;
import org.apache.tools.ant.types.Commandline;
import org.apache.tools.ant.types.DirSet;
import org.apache.tools.ant.types.EnumeratedAttribute;
import org.apache.tools.ant.types.FileSet;
import org.apache.tools.ant.types.Path;
import org.apache.tools.ant.types.PatternSet;
import org.apache.tools.ant.types.Reference;
import org.apache.tools.ant.types.Resource;
import org.apache.tools.ant.types.ResourceCollection;
import org.apache.tools.ant.types.resources.FileProvider;
import org.apache.tools.ant.util.FileUtils;
import org.apache.tools.ant.util.JavaEnvUtils;

Generates Javadoc documentation for a collection
of source code.
Current known limitations are:

   
patterns must be of the form "xxx.*", every other pattern doesn't
       work.
   
there is no control on arguments sanity since they are left
       to the Javadoc implementation.

If no doclet is set, then the version and
author are by default "yes".
Note: This task is run on another VM because the Javadoc code calls
System.exit() which would break Ant functionality.
Since:
Ant 1.1
@ant.task
category="java"/**
 * Generates Javadoc documentation for a collection
 * of source code.
 *
 * <p>Current known limitations are:</p>
 *
 * <ul>
 *    <li>patterns must be of the form "xxx.*", every other pattern doesn't
 *        work.
 *    <li>there is no control on arguments sanity since they are left
 *        to the Javadoc implementation.
 * </ul>
 *
 * <p>If no <code>doclet</code> is set, then the <code>version</code> and
 * <code>author</code> are by default <code>"yes"</code>.</p>
 *
 * <p>Note: This task is run on another VM because the Javadoc code calls
 * <code>System.exit()</code> which would break Ant functionality.</p>
 *
 * @since Ant 1.1
 *
 * @ant.task category="java"
 */
public class Javadoc extends Task {

    private static final String LOAD_FRAME = "function loadFrames() {";
    private static final int LOAD_FRAME_LEN = LOAD_FRAME.length();

    
Inner class used to manage doclet parameters.
/**
     * Inner class used to manage doclet parameters.
     */
    public class DocletParam {
        
The parameter name /** The parameter name */
        private String name;

        
The parameter value /** The parameter value */
        private String value;

        
Set the name of the parameter.
Params:
name – the name of the doclet parameter/**
         * Set the name of the parameter.
         *
         * @param name the name of the doclet parameter
         */
        public void setName(final String name) {
            this.name = name;
        }

        
Get the parameter name.
Returns:
the parameter's name./**
         * Get the parameter name.
         *
         * @return the parameter's name.
         */
        public String getName() {
            return name;
        }

        
Set the parameter value.
Note that only string values are supported. No resolution of file
paths is performed.
Params:
value – the parameter value./**
         * Set the parameter value.
         *
         * Note that only string values are supported. No resolution of file
         * paths is performed.
         *
         * @param value the parameter value.
         */
        public void setValue(final String value) {
            this.value = value;
        }

        
Get the parameter value.
Returns:
the parameter value./**
         * Get the parameter value.
         *
         * @return the parameter value.
         */
        public String getValue() {
            return value;
        }
    }

    
A project aware class used for Javadoc extensions which take a name
and a path such as doclet and taglet arguments.
/**
     * A project aware class used for Javadoc extensions which take a name
     * and a path such as doclet and taglet arguments.
     *
     */
    public static class ExtensionInfo extends ProjectComponent {
        
The name of the extension /** The name of the extension */
        private String name;

        
The optional path to use to load the extension /** The optional path to use to load the extension */
        private Path path;

        
Set the name of the extension
Params:
name – the extension's name./**
         * Set the name of the extension
         *
         * @param name the extension's name.
         */
        public void setName(final String name) {
            this.name = name;
        }

        
Get the name of the extension.
Returns:
the extension's name./**
         * Get the name of the extension.
         *
         * @return the extension's name.
         */
        public String getName() {
            return name;
        }

        
Set the path to use when loading the component.
Params:
path – a Path instance containing the classpath to use./**
         * Set the path to use when loading the component.
         *
         * @param path a Path instance containing the classpath to use.
         */
        public void setPath(final Path path) {
            if (this.path == null) {
                this.path = path;
            } else {
                this.path.append(path);
            }
        }

        
Get the extension's path.
Returns:
the path to be used to load the extension.
May be null/**
         * Get the extension's path.
         *
         * @return the path to be used to load the extension.
         * May be <code>null</code>
         */
        public Path getPath() {
            return path;
        }

        
Create an empty nested path to be configured by Ant with the
classpath for the extension.
Returns:
a new Path instance to be configured./**
         * Create an empty nested path to be configured by Ant with the
         * classpath for the extension.
         *
         * @return a new Path instance to be configured.
         */
        public Path createPath() {
            if (path == null) {
                path = new Path(getProject());
            }
            return path.createPath();
        }

        
Adds a reference to a CLASSPATH defined elsewhere.
Params:
r – the reference containing the path./**
         * Adds a reference to a CLASSPATH defined elsewhere.
         *
         * @param r the reference containing the path.
         */
        public void setPathRef(final Reference r) {
            createPath().setRefid(r);
        }
    }

    
This class stores info about doclets.
/**
     * This class stores info about doclets.
     *
     */
    public class DocletInfo extends ExtensionInfo {

        
Collection of doclet parameters. /** Collection of doclet parameters. */
        private final List<DocletParam> params = new Vector<>();

        
Create a doclet parameter to be configured by Ant.
Returns:
a new DocletParam instance to be configured./**
         * Create a doclet parameter to be configured by Ant.
         *
         * @return a new DocletParam instance to be configured.
         */
        public DocletParam createParam() {
            final DocletParam param = new DocletParam();
            params.add(param);
            return param;
        }

        
Get the doclet's parameters.
Returns:
an Enumeration of DocletParam instances./**
         * Get the doclet's parameters.
         *
         * @return an Enumeration of DocletParam instances.
         */
        public Enumeration<DocletParam> getParams() {
            return Collections.enumeration(params);
        }
    }

    
Used to track info about the packages to be javadoc'd
/**
     * Used to track info about the packages to be javadoc'd
     */
    public static class PackageName {
        
The package name /** The package name */
        private String name;

        
Set the name of the package
Params:
name – the package name./**
         * Set the name of the package
         *
         * @param name the package name.
         */
        public void setName(final String name) {
            this.name = name.trim();
        }

        
Get the package name.
Returns:
the package's name./**
         * Get the package name.
         *
         * @return the package's name.
         */
        public String getName() {
            return name;
        }

        
Return a string rep for this object.
Returns:
the package name./**
         * Return a string rep for this object.
         * @return the package name.
         */
        @Override
        public String toString() {
            return getName();
        }
    }

    
This class is used to manage the source files to be processed.
/**
     * This class is used to manage the source files to be processed.
     */
    public static class SourceFile {
        
The source file /** The source file */
        private File file;

        
Default constructor
/**
         * Default constructor
         */
        public SourceFile() {
            //empty
        }

        
Constructor specifying the source file directly
Params:
file – the source file/**
         * Constructor specifying the source file directly
         *
         * @param file the source file
         */
        public SourceFile(final File file) {
            this.file = file;
        }

        
Set the source file.
Params:
file – the source file./**
         * Set the source file.
         *
         * @param file the source file.
         */
        public void setFile(final File file) {
            this.file = file;
        }

        
Get the source file.
Returns:
the source file./**
         * Get the source file.
         *
         * @return the source file.
         */
        public File getFile() {
            return file;
        }
    }

    
An HTML element in the Javadoc.
This class is used for those Javadoc elements which contain HTML such as
footers, headers, etc.
/**
     * An HTML element in the Javadoc.
     *
     * This class is used for those Javadoc elements which contain HTML such as
     * footers, headers, etc.
     */
    public static class Html {
        
The text for the element /** The text for the element */
        private final StringBuffer text = new StringBuffer();

        
Add text to the element.
Params:
t – the text to be added./**
         * Add text to the element.
         *
         * @param t the text to be added.
         */
        public void addText(final String t) {
            text.append(t);
        }

        
Get the current text for the element.
Returns:
the current text./**
         * Get the current text for the element.
         *
         * @return the current text.
         */
        public String getText() {
            return text.substring(0);
        }
    }

    
EnumeratedAttribute implementation supporting the Javadoc scoping
values.
/**
     * EnumeratedAttribute implementation supporting the Javadoc scoping
     * values.
     */
    public static class AccessType extends EnumeratedAttribute {
        
Returns:
the allowed values for the access type./**
         * @return the allowed values for the access type.
         */
        @Override
        public String[] getValues() {
            // Protected first so if any GUI tool offers a default
            // based on enum #0, it will be right.
            return new String[] {"protected", "public", "package", "private"};
        }
    }

    
Holds a collection of ResourceCollections.
A separate kind of container is needed since this task
contains special handling for FileSets that has to occur at
task runtime.
/**
     * Holds a collection of ResourceCollections.
     *
     * <p>A separate kind of container is needed since this task
     * contains special handling for FileSets that has to occur at
     * task runtime.</p>
     */
    public class ResourceCollectionContainer
        implements Iterable<ResourceCollection> {

        private final List<ResourceCollection> rcs = new ArrayList<>();

        
Add a resource collection to the container.
Params:
rc – the collection to add./**
         * Add a resource collection to the container.
         * @param rc the collection to add.
         */
        public void add(final ResourceCollection rc) {
            rcs.add(rc);
        }

        
Get an iterator on the collection.
Returns:
an iterator./**
         * Get an iterator on the collection.
         * @return an iterator.
         */
        @Override
        public Iterator<ResourceCollection> iterator() {
            return rcs.iterator();
        }
    }

    private static final FileUtils FILE_UTILS = FileUtils.getFileUtils();

    
The command line built to execute Javadoc. /** The command line built to execute Javadoc. */
    private final Commandline cmd = new Commandline();

    
Utility method to add an argument to the command line conditionally
based on the given flag.
Params:
b – the flag which controls if the argument is added.
arg – the argument value./**
     * Utility method to add an argument to the command line conditionally
     * based on the given flag.
     *
     * @param b the flag which controls if the argument is added.
     * @param arg the argument value.
     */
    private void addArgIf(final boolean b, final String arg) {
        if (b) {
            cmd.createArgument().setValue(arg);
        }
    }

    
Utility method to add a Javadoc argument.
Params:
key – the argument name.
value – the argument value./**
     * Utility method to add a Javadoc argument.
     *
     * @param key the argument name.
     * @param value the argument value.
     */
    private void addArgIfNotEmpty(final String key, final String value) {
        if (value == null || value.isEmpty()) {
            log("Warning: Leaving out empty argument '" + key + "'",
                Project.MSG_WARN);
        } else {
            cmd.createArgument().setValue(key);
            cmd.createArgument().setValue(value);
        }
    }

    
Flag which indicates if the task should fail if there is a
Javadoc error.
/**
     * Flag which indicates if the task should fail if there is a
     * Javadoc error.
     */
    private boolean failOnError = false;
    
Flag which indicates if the task should fail if there is a
Javadoc warning.
/**
     * Flag which indicates if the task should fail if there is a
     * Javadoc warning.
     */
    private boolean failOnWarning = false;
    private Path sourcePath = null;
    private File destDir = null;
    private final List<SourceFile> sourceFiles = new Vector<>();
    private final List<PackageName> packageNames = new Vector<>();
    private final List<PackageName> excludePackageNames = new Vector<>(1);
    private final List<PackageName> moduleNames = new ArrayList<>();
    private boolean author = true;
    private boolean version = true;
    private DocletInfo doclet = null;
    private Path classpath = null;
    private Path bootclasspath = null;
    private Path modulePath = null;
    private Path moduleSourcePath = null;
    private String group = null;
    private String packageList = null;
    private final List<LinkArgument> links = new Vector<>();
    private final List<GroupArgument> groups = new Vector<>();
    private final List<Object> tags = new Vector<>();
    private boolean useDefaultExcludes = true;
    private Html doctitle = null;
    private Html header = null;
    private Html footer = null;
    private Html bottom = null;
    private boolean useExternalFile = false;
    private String source = null;
    private boolean linksource = false;
    private boolean breakiterator = false;
    private String noqualifier;
    private boolean includeNoSourcePackages = false;
    private String executable = null;
    private boolean docFilesSubDirs = false;
    private String excludeDocFilesSubDir = null;
    private String docEncoding = null;
    private boolean postProcessGeneratedJavadocs = true;

    private final ResourceCollectionContainer nestedSourceFiles
        = new ResourceCollectionContainer();
    private final List<DirSet> packageSets = new Vector<>();

    
Work around command line length limit by using an external file
for the sourcefiles.
Params:
b – true if an external file is to be used./**
     * Work around command line length limit by using an external file
     * for the sourcefiles.
     *
     * @param b true if an external file is to be used.
     */
    public void setUseExternalFile(final boolean b) {
        useExternalFile = b;
    }

    
Sets whether default exclusions should be used or not.
Params:
useDefaultExcludes – "true"|"on"|"yes" when default exclusions
                          should be used, "false"|"off"|"no" when they
                          shouldn't be used./**
     * Sets whether default exclusions should be used or not.
     *
     * @param useDefaultExcludes "true"|"on"|"yes" when default exclusions
     *                           should be used, "false"|"off"|"no" when they
     *                           shouldn't be used.
     */
    public void setDefaultexcludes(final boolean useDefaultExcludes) {
        this.useDefaultExcludes = useDefaultExcludes;
    }

    
Set the maximum memory to be used by the javadoc process
Params:
max – a string indicating the maximum memory according to the
       JVM conventions (e.g. 128m is 128 Megabytes)/**
     * Set the maximum memory to be used by the javadoc process
     *
     * @param max a string indicating the maximum memory according to the
     *        JVM conventions (e.g. 128m is 128 Megabytes)
     */
    public void setMaxmemory(final String max) {
        cmd.createArgument().setValue("-J-Xmx" + max);
    }

    
Set an additional parameter on the command line
Params:
add – the additional command line parameter for the javadoc task./**
     * Set an additional parameter on the command line
     *
     * @param add the additional command line parameter for the javadoc task.
     */
    public void setAdditionalparam(final String add) {
        cmd.createArgument().setLine(add);
    }

    
Adds a command-line argument.
Returns:
a command-line argument to configure
Since:
Ant 1.6/**
     * Adds a command-line argument.
     * @return a command-line argument to configure
     * @since Ant 1.6
     */
    public Commandline.Argument createArg() {
        return cmd.createArgument();
    }

    
Specify where to find source file
Params:
src – a Path instance containing the various source directories./**
     * Specify where to find source file
     *
     * @param src a Path instance containing the various source directories.
     */
    public void setSourcepath(final Path src) {
        if (sourcePath == null) {
            sourcePath = src;
        } else {
            sourcePath.append(src);
        }
    }

    
Create a path to be configured with the locations of the source
files.
Returns:
a new Path instance to be configured by the Ant core./**
     * Create a path to be configured with the locations of the source
     * files.
     *
     * @return a new Path instance to be configured by the Ant core.
     */
    public Path createSourcepath() {
        if (sourcePath == null) {
            sourcePath = new Path(getProject());
        }
        return sourcePath.createPath();
    }

    
Adds a reference to a CLASSPATH defined elsewhere.
Params:
r – the reference containing the source path definition./**
     * Adds a reference to a CLASSPATH defined elsewhere.
     *
     * @param r the reference containing the source path definition.
     */
    public void setSourcepathRef(final Reference r) {
        createSourcepath().setRefid(r);
    }

    
Specify where to find modules
Params:
mp – a Path instance containing the modules.
Since:
Ant 1.10.6/**
     * Specify where to find modules
     *
     * @param mp a Path instance containing the modules.
     *
     * @since Ant 1.10.6
     */
    public void setModulePath(final Path mp) {
        if (modulePath == null) {
            modulePath = mp;
        } else {
            modulePath.append(mp);
        }
    }

    
Create a path to be configured with the locations of the module
files.
Returns:
a new Path instance to be configured by the Ant core.
Since:
Ant 1.10.6/**
     * Create a path to be configured with the locations of the module
     * files.
     *
     * @return a new Path instance to be configured by the Ant core.
     *
     * @since Ant 1.10.6
     */
    public Path createModulePath() {
        if (modulePath == null) {
            modulePath = new Path(getProject());
        }
        return modulePath.createPath();
    }

    
Adds a reference to a path defined elsewhere that defines the module path.
Params:
r – the reference containing the module path definition.
Since:
Ant 1.10.6/**
     * Adds a reference to a path defined elsewhere that defines the module path.
     *
     * @param r the reference containing the module path definition.
     *
     * @since Ant 1.10.6
     */
    public void setModulePathref(final Reference r) {
        createModulePath().setRefid(r);
    }

    
Specify where to find sources for modules
Params:
mp – a Path instance containing the sources for modules.
Since:
Ant 1.10.6/**
     * Specify where to find sources for modules
     *
     * @param mp a Path instance containing the sources for modules.
     *
     * @since Ant 1.10.6
     */
    public void setModuleSourcePath(final Path mp) {
        if (moduleSourcePath == null) {
            moduleSourcePath = mp;
        } else {
            moduleSourcePath.append(mp);
        }
    }

    
Create a path to be configured with the locations of the module
source files.
Returns:
a new Path instance to be configured by the Ant core.
Since:
Ant 1.10.6/**
     * Create a path to be configured with the locations of the module
     * source files.
     *
     * @return a new Path instance to be configured by the Ant core.
     *
     * @since Ant 1.10.6
     */
    public Path createModuleSourcePath() {
        if (moduleSourcePath == null) {
            moduleSourcePath = new Path(getProject());
        }
        return moduleSourcePath.createPath();
    }

    
Adds a reference to a path defined elsewhere that defines the module source path.
Params:
r – the reference containing the module source path definition.
Since:
Ant 1.10.6/**
     * Adds a reference to a path defined elsewhere that defines the module source path.
     *
     * @param r the reference containing the module source path definition.
     *
     * @since Ant 1.10.6
     */
    public void setModuleSourcePathref(final Reference r) {
        createModuleSourcePath().setRefid(r);
    }

    
Set the directory where the Javadoc output will be generated.
Params:
dir – the destination directory./**
     * Set the directory where the Javadoc output will be generated.
     *
     * @param dir the destination directory.
     */
    public void setDestdir(final File dir) {
        destDir = dir;
        cmd.createArgument().setValue("-d");
        cmd.createArgument().setFile(destDir);
    }

    
Set the list of source files to process.
Params:
src – a comma separated list of source files./**
     * Set the list of source files to process.
     *
     * @param src a comma separated list of source files.
     */
    public void setSourcefiles(final String src) {
        final StringTokenizer tok = new StringTokenizer(src, ",");
        while (tok.hasMoreTokens()) {
            final String f = tok.nextToken();
            final SourceFile sf = new SourceFile();
            sf.setFile(getProject().resolveFile(f.trim()));
            addSource(sf);
        }
    }

    
Add a single source file.
Params:
sf – the source file to be processed./**
     * Add a single source file.
     *
     * @param sf the source file to be processed.
     */
    public void addSource(final SourceFile sf) {
        sourceFiles.add(sf);
    }

    
Set the package names to be processed.
Params:
packages – a comma separated list of packages specs
       (may be wildcarded).
See Also:
for wildcard information./**
     * Set the package names to be processed.
     *
     * @param packages a comma separated list of packages specs
     *        (may be wildcarded).
     *
     * @see #addPackage for wildcard information.
     */
    public void setPackagenames(final String packages) {
        final StringTokenizer tok = new StringTokenizer(packages, ",");
        while (tok.hasMoreTokens()) {
            final String p = tok.nextToken();
            final PackageName pn = new PackageName();
            pn.setName(p);
            addPackage(pn);
        }
    }

    
Set the module names to be processed.
Params:
modules – a comma separated list of module names
Since:
Ant 1.10.6/**
     * Set the module names to be processed.
     *
     * @param modules a comma separated list of module names
     *
     * @since Ant 1.10.6
     */
    public void setModulenames(final String modules) {
        for (String m : modules.split(",")) {
            final PackageName mn = new PackageName();
            mn.setName(m);
            addModule(mn);
        }
    }

    
Add a single package to be processed.
If the package name ends with ".*" the Javadoc task
will find and process all subpackages.
Params:
pn – the package name, possibly wildcarded./**
     * Add a single package to be processed.
     *
     * If the package name ends with &quot;.*&quot; the Javadoc task
     * will find and process all subpackages.
     *
     * @param pn the package name, possibly wildcarded.
     */
    public void addPackage(final PackageName pn) {
        packageNames.add(pn);
    }

    
Add a single module to be processed.
Params:
mn – the module name
Since:
Ant 1.10.6/**
     * Add a single module to be processed.
     *
     * @param mn the module name
     *
     * @since Ant 1.10.6
     */
    public void addModule(final PackageName mn) {
        moduleNames.add(mn);
    }

    
Set the list of packages to be excluded.
Params:
packages – a comma separated list of packages to be excluded.
       This may not include wildcards./**
     * Set the list of packages to be excluded.
     *
     * @param packages a comma separated list of packages to be excluded.
     *        This may not include wildcards.
     */
    public void setExcludePackageNames(final String packages) {
        final StringTokenizer tok = new StringTokenizer(packages, ",");
        while (tok.hasMoreTokens()) {
            final String p = tok.nextToken();
            final PackageName pn = new PackageName();
            pn.setName(p);
            addExcludePackage(pn);
        }
    }

    
Add a package to be excluded from the Javadoc run.
Params:
pn – the name of the package (wildcards are not permitted)./**
     * Add a package to be excluded from the Javadoc run.
     *
     * @param pn the name of the package (wildcards are not permitted).
     */
    public void addExcludePackage(final PackageName pn) {
        excludePackageNames.add(pn);
    }

    
Specify the file containing the overview to be included in the generated
documentation.
Params:
f – the file containing the overview./**
     * Specify the file containing the overview to be included in the generated
     * documentation.
     *
     * @param f the file containing the overview.
     */
    public void setOverview(final File f) {
        cmd.createArgument().setValue("-overview");
        cmd.createArgument().setFile(f);
    }

    
Indicate whether only public classes and members are to be included in
the scope processed
Params:
b – true if scope is to be public./**
     * Indicate whether only public classes and members are to be included in
     * the scope processed
     *
     * @param b true if scope is to be public.
     */
    public void setPublic(final boolean b) {
        addArgIf(b, "-public");
    }

    
Indicate whether only protected and public classes and members are to
be included in the scope processed
Params:
b – true if scope is to be protected./**
     * Indicate whether only protected and public classes and members are to
     * be included in the scope processed
     *
     * @param b true if scope is to be protected.
     */
    public void setProtected(final boolean b) {
        addArgIf(b, "-protected");
    }

    
Indicate whether only package, protected and public classes and
members are to be included in the scope processed
Params:
b – true if scope is to be package level./**
     * Indicate whether only package, protected and public classes and
     * members are to be included in the scope processed
     *
     * @param b true if scope is to be package level.
     */
    public void setPackage(final boolean b) {
        addArgIf(b, "-package");
    }

    
Indicate whether all classes and
members are to be included in the scope processed
Params:
b – true if scope is to be private level./**
     * Indicate whether all classes and
     * members are to be included in the scope processed
     *
     * @param b true if scope is to be private level.
     */
    public void setPrivate(final boolean b) {
        addArgIf(b, "-private");
    }

    
Set the scope to be processed. This is an alternative to the
use of the setPublic, setPrivate, etc methods. It gives better build
file control over what scope is processed.
Params:
at – the scope to be processed./**
     * Set the scope to be processed. This is an alternative to the
     * use of the setPublic, setPrivate, etc methods. It gives better build
     * file control over what scope is processed.
     *
     * @param at the scope to be processed.
     */
    public void setAccess(final AccessType at) {
        cmd.createArgument().setValue("-" + at.getValue());
    }

    
Set the class that starts the doclet used in generating the
documentation.
Params:
docletName – the name of the doclet class./**
     * Set the class that starts the doclet used in generating the
     * documentation.
     *
     * @param docletName the name of the doclet class.
     */
    public void setDoclet(final String docletName) {
        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.setName(docletName);
    }

    
Set the classpath used to find the doclet class.
Params:
docletPath – the doclet classpath./**
     * Set the classpath used to find the doclet class.
     *
     * @param docletPath the doclet classpath.
     */
    public void setDocletPath(final Path docletPath) {
        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.setPath(docletPath);
    }

    
Set the classpath used to find the doclet class by reference.
Params:
r – the reference to the Path instance to use as the doclet
       classpath./**
     * Set the classpath used to find the doclet class by reference.
     *
     * @param r the reference to the Path instance to use as the doclet
     *        classpath.
     */
    public void setDocletPathRef(final Reference r) {
        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.createPath().setRefid(r);
    }

    
Create a doclet to be used in the documentation generation.
Returns:
a new DocletInfo instance to be configured./**
     * Create a doclet to be used in the documentation generation.
     *
     * @return a new DocletInfo instance to be configured.
     */
    public DocletInfo createDoclet() {
        if (doclet == null) {
            doclet = new DocletInfo();
        }
        return doclet;
    }

    
Add a taglet
Params:
tagletInfo – information about the taglet./**
     * Add a taglet
     *
     * @param tagletInfo information about the taglet.
     */
    public void addTaglet(final ExtensionInfo tagletInfo) {
        tags.add(tagletInfo);
    }

    
Indicate whether Javadoc should produce old style (JDK 1.1)
documentation.
This is not supported by JDK 1.1 and has been phased out in JDK 1.4
Params:
b – if true attempt to generate old style documentation./**
     * Indicate whether Javadoc should produce old style (JDK 1.1)
     * documentation.
     *
     * This is not supported by JDK 1.1 and has been phased out in JDK 1.4
     *
     * @param b if true attempt to generate old style documentation.
     */
    public void setOld(final boolean b) {
        log("Javadoc 1.4 doesn't support the -1.1 switch anymore",
            Project.MSG_WARN);
    }

    
Set the classpath to be used for this Javadoc run.
Params:
path – an Ant Path object containing the compilation
       classpath./**
     * Set the classpath to be used for this Javadoc run.
     *
     * @param path an Ant Path object containing the compilation
     *        classpath.
     */
    public void setClasspath(final Path path) {
        if (classpath == null) {
            classpath = path;
        } else {
            classpath.append(path);
        }
    }

    
Create a Path to be configured with the classpath to use
Returns:
a new Path instance to be configured with the classpath./**
     * Create a Path to be configured with the classpath to use
     *
     * @return a new Path instance to be configured with the classpath.
     */
    public Path createClasspath() {
        if (classpath == null) {
            classpath = new Path(getProject());
        }
        return classpath.createPath();
    }

    
Adds a reference to a CLASSPATH defined elsewhere.
Params:
r – the reference to an instance defining the classpath./**
     * Adds a reference to a CLASSPATH defined elsewhere.
     *
     * @param r the reference to an instance defining the classpath.
     */
    public void setClasspathRef(final Reference r) {
        createClasspath().setRefid(r);
    }

    
Set the boot classpath to use.
Params:
path – the boot classpath./**
     * Set the boot classpath to use.
     *
     * @param path the boot classpath.
     */
    public void setBootclasspath(final Path path) {
        if (bootclasspath == null) {
            bootclasspath = path;
        } else {
            bootclasspath.append(path);
        }
    }

    
Create a Path to be configured with the boot classpath
Returns:
a new Path instance to be configured with the boot classpath./**
     * Create a Path to be configured with the boot classpath
     *
     * @return a new Path instance to be configured with the boot classpath.
     */
    public Path createBootclasspath() {
        if (bootclasspath == null) {
            bootclasspath = new Path(getProject());
        }
        return bootclasspath.createPath();
    }

    
Adds a reference to a CLASSPATH defined elsewhere.
Params:
r – the reference to an instance defining the bootclasspath./**
     * Adds a reference to a CLASSPATH defined elsewhere.
     *
     * @param r the reference to an instance defining the bootclasspath.
     */
    public void setBootClasspathRef(final Reference r) {
        createBootclasspath().setRefid(r);
    }

    
Set the location of the extensions directories.
Params:
path – the string version of the path.
Deprecated:
since 1.5.x. Use the setExtdirs(Path) version./**
     * Set the location of the extensions directories.
     *
     * @param path the string version of the path.
     * @deprecated since 1.5.x.
     *             Use the {@link #setExtdirs(Path)} version.
     */
    @Deprecated
    public void setExtdirs(final String path) {
        cmd.createArgument().setValue("-extdirs");
        cmd.createArgument().setValue(path);
    }

    
Set the location of the extensions directories.
Params:
path – a path containing the extension directories./**
     * Set the location of the extensions directories.
     *
     * @param path a path containing the extension directories.
     */
    public void setExtdirs(final Path path) {
        cmd.createArgument().setValue("-extdirs");
        cmd.createArgument().setPath(path);
    }

    
Run javadoc in verbose mode
Params:
b – true if operation is to be verbose./**
     * Run javadoc in verbose mode
     *
     * @param b true if operation is to be verbose.
     */
    public void setVerbose(final boolean b) {
        addArgIf(b, "-verbose");
    }

    
Set the local to use in documentation generation.
Params:
locale – the locale to use./**
     * Set the local to use in documentation generation.
     *
     * @param locale the locale to use.
     */
    public void setLocale(final String locale) {
        // createArgument(true) is necessary to make sure -locale
        // is the first argument (required in 1.3+).
        cmd.createArgument(true).setValue(locale);
        cmd.createArgument(true).setValue("-locale");
    }

    
Set the encoding name of the source files,
Params:
enc – the name of the encoding for the source files./**
     * Set the encoding name of the source files,
     *
     * @param enc the name of the encoding for the source files.
     */
    public void setEncoding(final String enc) {
        cmd.createArgument().setValue("-encoding");
        cmd.createArgument().setValue(enc);
    }

    
Include the version tag in the generated documentation.
Params:
b – true if the version tag should be included./**
     * Include the version tag in the generated documentation.
     *
     * @param b true if the version tag should be included.
     */
    public void setVersion(final boolean b) {
        this.version = b;
    }

    
Generate the "use" page for each package.
Params:
b – true if the use page should be generated./**
     * Generate the &quot;use&quot; page for each package.
     *
     * @param b true if the use page should be generated.
     */
    public void setUse(final boolean b) {
        addArgIf(b, "-use");
    }


    
Include the author tag in the generated documentation.
Params:
b – true if the author tag should be included./**
     * Include the author tag in the generated documentation.
     *
     * @param b true if the author tag should be included.
     */
    public void setAuthor(final boolean b) {
        author = b;
    }

    
Generate a split index
Params:
b – true if the index should be split into a file per letter./**
     * Generate a split index
     *
     * @param b true if the index should be split into a file per letter.
     */
    public void setSplitindex(final boolean b) {
        addArgIf(b, "-splitindex");
    }

    
Set the title to be placed in the HTML <title> tag of the
generated documentation.
Params:
title – the window title to use./**
     * Set the title to be placed in the HTML &lt;title&gt; tag of the
     * generated documentation.
     *
     * @param title the window title to use.
     */
    public void setWindowtitle(final String title) {
        addArgIfNotEmpty("-windowtitle", title);
    }

    
Set the title of the generated overview page.
Params:
doctitle – the Document title./**
     * Set the title of the generated overview page.
     *
     * @param doctitle the Document title.
     */
    public void setDoctitle(final String doctitle) {
        final Html h = new Html();
        h.addText(doctitle);
        addDoctitle(h);
    }

    
Add a document title to use for the overview page.
Params:
text – the HTML element containing the document title./**
     * Add a document title to use for the overview page.
     *
     * @param text the HTML element containing the document title.
     */
    public void addDoctitle(final Html text) {
        doctitle = text;
    }

    
Set the header text to be placed at the top of each output file.
Params:
header – the header text/**
     * Set the header text to be placed at the top of each output file.
     *
     * @param header the header text
     */
    public void setHeader(final String header) {
        final Html h = new Html();
        h.addText(header);
        addHeader(h);
    }

    
Set the header text to be placed at the top of each output file.
Params:
text – the header text/**
     * Set the header text to be placed at the top of each output file.
     *
     * @param text the header text
     */
    public void addHeader(final Html text) {
        header = text;
    }

    
Set the footer text to be placed at the bottom of each output file.
Params:
footer – the footer text./**
     * Set the footer text to be placed at the bottom of each output file.
     *
     * @param footer the footer text.
     */
    public void setFooter(final String footer) {
        final Html h = new Html();
        h.addText(footer);
        addFooter(h);
    }

    
Set the footer text to be placed at the bottom of each output file.
Params:
text – the footer text./**
     * Set the footer text to be placed at the bottom of each output file.
     *
     * @param text the footer text.
     */
    public void addFooter(final Html text) {
        footer = text;
    }

    
Set the text to be placed at the bottom of each output file.
Params:
bottom – the bottom text./**
     * Set the text to be placed at the bottom of each output file.
     *
     * @param bottom the bottom text.
     */
    public void setBottom(final String bottom) {
        final Html h = new Html();
        h.addText(bottom);
        addBottom(h);
    }

    
Set the text to be placed at the bottom of each output file.
Params:
text – the bottom text./**
     * Set the text to be placed at the bottom of each output file.
     *
     * @param text the bottom text.
     */
    public void addBottom(final Html text) {
        bottom = text;
    }

    
Link to docs at "url" using package list at "url2"
- separate the URLs by using a space character.
Params:
src – the offline link specification (url and package list)/**
     * Link to docs at "url" using package list at "url2"
     * - separate the URLs by using a space character.
     *
     * @param src the offline link specification (url and package list)
     */
    public void setLinkoffline(final String src) {
        final LinkArgument le = createLink();
        le.setOffline(true);
        final String linkOfflineError = "The linkoffline attribute must include"
            + " a URL and a package-list file location separated by a"
            + " space";
        if (src.trim().isEmpty()) {
            throw new BuildException(linkOfflineError);
        }
        final StringTokenizer tok = new StringTokenizer(src, " ", false);
        le.setHref(tok.nextToken());

        if (!tok.hasMoreTokens()) {
            throw new BuildException(linkOfflineError);
        }
        le.setPackagelistLoc(getProject().resolveFile(tok.nextToken()));
    }

    
Group specified packages together in overview page.
Params:
src – the group packages - a command separated list of group specs,
       each one being a group name and package specification separated
       by a space./**
     * Group specified packages together in overview page.
     *
     * @param src the group packages - a command separated list of group specs,
     *        each one being a group name and package specification separated
     *        by a space.
     */
    public void setGroup(final String src) {
        group = src;
    }

    
Create links to Javadoc output at the given URL.
Params:
src – the URL to link to/**
     * Create links to Javadoc output at the given URL.
     * @param src the URL to link to
     */
    public void setLink(final String src) {
        createLink().setHref(src);
    }

    
Control deprecation information
Params:
b – If true, do not include deprecated information./**
     * Control deprecation information
     *
     * @param b If true, do not include deprecated information.
     */
    public void setNodeprecated(final boolean b) {
        addArgIf(b, "-nodeprecated");
    }

    
Control deprecated list generation
Params:
b – if true, do not generate deprecated list./**
     * Control deprecated list generation
     *
     * @param b if true, do not generate deprecated list.
     */
    public void setNodeprecatedlist(final boolean b) {
        addArgIf(b, "-nodeprecatedlist");
    }

    
Control class tree generation.
Params:
b – if true, do not generate class hierarchy./**
     * Control class tree generation.
     *
     * @param b if true, do not generate class hierarchy.
     */
    public void setNotree(final boolean b) {
        addArgIf(b, "-notree");
    }

    
Control generation of index.
Params:
b – if true, do not generate index./**
     * Control generation of index.
     *
     * @param b if true, do not generate index.
     */
    public void setNoindex(final boolean b) {
        addArgIf(b, "-noindex");
    }

    
Control generation of help link.
Params:
b – if true, do not generate help link/**
     * Control generation of help link.
     *
     * @param b if true, do not generate help link
     */
    public void setNohelp(final boolean b) {
        addArgIf(b, "-nohelp");
    }

    
Control generation of the navigation bar.
Params:
b – if true, do not generate navigation bar./**
     * Control generation of the navigation bar.
     *
     * @param b if true, do not generate navigation bar.
     */
    public void setNonavbar(final boolean b) {
        addArgIf(b, "-nonavbar");
    }

    
Control warnings about serial tag.
Params:
b – if true, generate warning about the serial tag./**
     * Control warnings about serial tag.
     *
     * @param b if true, generate warning about the serial tag.
     */
    public void setSerialwarn(final boolean b) {
        addArgIf(b, "-serialwarn");
    }

    
Specifies the CSS stylesheet file to use.
Params:
f – the file with the CSS to use./**
     * Specifies the CSS stylesheet file to use.
     *
     * @param f the file with the CSS to use.
     */
    public void setStylesheetfile(final File f) {
        cmd.createArgument().setValue("-stylesheetfile");
        cmd.createArgument().setFile(f);
    }

    
Specifies the HTML help file to use.
Params:
f – the file containing help content./**
     * Specifies the HTML help file to use.
     *
     * @param f the file containing help content.
     */
    public void setHelpfile(final File f) {
        cmd.createArgument().setValue("-helpfile");
        cmd.createArgument().setFile(f);
    }

    
Output file encoding name.
Params:
enc – name of the encoding to use./**
     * Output file encoding name.
     *
     * @param enc name of the encoding to use.
     */
    public void setDocencoding(final String enc) {
        cmd.createArgument().setValue("-docencoding");
        cmd.createArgument().setValue(enc);
        docEncoding = enc;
    }

    
The name of a file containing the packages to process.
Params:
src – the file containing the package list./**
     * The name of a file containing the packages to process.
     *
     * @param src the file containing the package list.
     */
    public void setPackageList(final String src) {
        packageList = src;
    }

    
Create link to Javadoc output at the given URL.
Returns:
link argument to configure/**
     * Create link to Javadoc output at the given URL.
     *
     * @return link argument to configure
     */
    public LinkArgument createLink() {
        final LinkArgument la = new LinkArgument();
        links.add(la);
        return la;
    }

    
Represents a link triplet (href, whether link is offline,
location of the package list if off line)
/**
     * Represents a link triplet (href, whether link is offline,
     * location of the package list if off line)
     */
    public class LinkArgument {
        private String href;
        private boolean offline = false;
        private File packagelistLoc;
        private URL packagelistURL;
        private boolean resolveLink = false;

        
Constructor for LinkArgument /** Constructor for LinkArgument */
        public LinkArgument() {
            //empty
        }

        
Set the href attribute.
Params:
hr – a String value/**
         * Set the href attribute.
         * @param hr a <code>String</code> value
         */
        public void setHref(final String hr) {
            href = hr;
        }

        
Get the href attribute.
Returns:
the href attribute./**
         * Get the href attribute.
         * @return the href attribute.
         */
        public String getHref() {
            return href;
        }

        
Set the packetlist location attribute.
Params:
src – a File value/**
         * Set the packetlist location attribute.
         * @param src a <code>File</code> value
         */
        public void setPackagelistLoc(final File src) {
            packagelistLoc = src;
        }

        
Get the packetList location attribute.
Returns:
the packetList location attribute./**
         * Get the packetList location attribute.
         * @return the packetList location attribute.
         */
        public File getPackagelistLoc() {
            return packagelistLoc;
        }

        
Set the packetlist location attribute.
Params:
src – an URL value/**
         * Set the packetlist location attribute.
         * @param src an <code>URL</code> value
         */
        public void setPackagelistURL(final URL src) {
            packagelistURL = src;
        }

        
Get the packetList location attribute.
Returns:
the packetList location attribute./**
         * Get the packetList location attribute.
         * @return the packetList location attribute.
         */
        public URL getPackagelistURL() {
            return packagelistURL;
        }

        
Set the offline attribute.
Params:
offline – a boolean value/**
         * Set the offline attribute.
         * @param offline a <code>boolean</code> value
         */
        public void setOffline(final boolean offline) {
            this.offline = offline;
        }

        
Get the linkOffline attribute.
Returns:
the linkOffline attribute./**
         * Get the linkOffline attribute.
         * @return the linkOffline attribute.
         */
        public boolean isLinkOffline() {
            return offline;
        }

        
Sets whether Ant should resolve the link attribute relative
to the current basedir.
Params:
resolve – a boolean value/**
         * Sets whether Ant should resolve the link attribute relative
         * to the current basedir.
         * @param resolve a <code>boolean</code> value
         */
        public void setResolveLink(final boolean resolve) {
            this.resolveLink = resolve;
        }

        
should Ant resolve the link attribute relative to the
current basedir?
Returns:
the resolveLink attribute./**
         * should Ant resolve the link attribute relative to the
         * current basedir?
         * @return the resolveLink attribute.
         */
        public boolean shouldResolveLink() {
            return resolveLink;
        }

    }

    
Creates and adds a -tag argument. This is used to specify
custom tags. This argument is only available for Javadoc 1.4,
and will generate a verbose message (and then be ignored)
when run on Java versions below 1.4.
Returns:
tag argument to be configured/**
     * Creates and adds a -tag argument. This is used to specify
     * custom tags. This argument is only available for Javadoc 1.4,
     * and will generate a verbose message (and then be ignored)
     * when run on Java versions below 1.4.
     * @return tag argument to be configured
     */
    public TagArgument createTag() {
        final TagArgument ta = new TagArgument();
        tags.add(ta);
        return ta;
    }

    
Scope element verbose names. (Defined here as fields
cannot be static in inner classes.) The first letter
from each element is used to build up the scope string.
/**
     * Scope element verbose names. (Defined here as fields
     * cannot be static in inner classes.) The first letter
     * from each element is used to build up the scope string.
     */
    static final String[] SCOPE_ELEMENTS = { //NOSONAR
        "overview", "packages", "types", "constructors",
        "methods", "fields"
    };

    
Class representing a -tag argument.
/**
     * Class representing a -tag argument.
     */
    public class TagArgument extends FileSet {
        
Name of the tag. /** Name of the tag. */
        private String name = null;
        
Whether or not the tag is enabled. /** Whether or not the tag is enabled. */
        private boolean enabled = true;
        
Scope string of the tag. This will form the middle
argument of the -tag parameter when the tag is enabled
(with an X prepended for and is parsed from human-readable form.
/**
         * Scope string of the tag. This will form the middle
         * argument of the -tag parameter when the tag is enabled
         * (with an X prepended for and is parsed from human-readable form.
         */
        private String scope = "a";

        
Sole constructor. /** Sole constructor. */
        public TagArgument() {
            //empty
        }

        
Sets the name of the tag.
Params:
name – The name of the tag.
            Must not be null or empty./**
         * Sets the name of the tag.
         *
         * @param name The name of the tag.
         *             Must not be <code>null</code> or empty.
         */
        public void setName(final String name) {
            this.name = name;
        }

        
Sets the scope of the tag. This is in comma-separated
form, with each element being one of "all" (the default),
"overview", "packages", "types", "constructors", "methods",
"fields". The elements are treated in a case-insensitive
manner.
Params:
verboseScope – The scope of the tag.
                    Must not be null,
                    should not be empty.
Throws:
BuildException – if all is specified along with
other elements, if any elements are repeated, if no
elements are specified, or if any unrecognised elements are
specified./**
         * Sets the scope of the tag. This is in comma-separated
         * form, with each element being one of "all" (the default),
         * "overview", "packages", "types", "constructors", "methods",
         * "fields". The elements are treated in a case-insensitive
         * manner.
         *
         * @param verboseScope The scope of the tag.
         *                     Must not be <code>null</code>,
         *                     should not be empty.
         *
         * @exception BuildException if all is specified along with
         * other elements, if any elements are repeated, if no
         * elements are specified, or if any unrecognised elements are
         * specified.
         */
        public void setScope(String verboseScope) throws BuildException {
            verboseScope = verboseScope.toLowerCase(Locale.ENGLISH);

            final boolean[] elements = new boolean[SCOPE_ELEMENTS.length];

            boolean gotAll = false;
            boolean gotNotAll = false;

            // Go through the tokens one at a time, updating the
            // elements array and issuing warnings where appropriate.
            final StringTokenizer tok = new StringTokenizer(verboseScope, ",");
            while (tok.hasMoreTokens()) {
                final String next = tok.nextToken().trim();
                if ("all".equals(next)) {
                    if (gotAll) {
                        getProject().log("Repeated tag scope element: all",
                                          Project.MSG_VERBOSE);
                    }
                    gotAll = true;
                } else {
                    int i;
                    for (i = 0; i < SCOPE_ELEMENTS.length; i++) {
                        if (SCOPE_ELEMENTS[i].equals(next)) {
                            break;
                        }
                    }
                    if (i == SCOPE_ELEMENTS.length) {
                        throw new BuildException(
                            "Unrecognised scope element: %s", next);
                    }
                    if (elements[i]) {
                        getProject().log("Repeated tag scope element: " + next,
                            Project.MSG_VERBOSE);
                    }
                    elements[i] = true;
                    gotNotAll = true;
                }
            }

            if (gotNotAll && gotAll) {
                throw new BuildException(
                    "Mixture of \"all\" and other scope elements in tag parameter.");
            }
            if (!gotNotAll && !gotAll) {
                throw new BuildException(
                    "No scope elements specified in tag parameter.");
            }
            if (gotAll) {
                this.scope = "a";
            } else {
                final StringBuilder buff = new StringBuilder(elements.length);
                for (int i = 0; i < elements.length; i++) {
                    if (elements[i]) {
                        buff.append(SCOPE_ELEMENTS[i].charAt(0));
                    }
                }
                this.scope = buff.toString();
            }
        }

        
Sets whether or not the tag is enabled.
Params:
enabled – Whether or not this tag is enabled./**
         * Sets whether or not the tag is enabled.
         *
         * @param enabled Whether or not this tag is enabled.
         */
        public void setEnabled(final boolean enabled) {
            this.enabled = enabled;
        }

        
Returns the -tag parameter this argument represented.
Throws:
BuildException – if either the name or description
                          is null or empty.
Returns:
the -tag parameter as a string/**
         * Returns the -tag parameter this argument represented.
         * @return the -tag parameter as a string
         * @exception BuildException if either the name or description
         *                           is <code>null</code> or empty.
         */
        public String getParameter() throws BuildException {
            if (name == null || name.isEmpty()) {
                throw new BuildException("No name specified for custom tag.");
            }
            if (getDescription() != null) {
                return name + ":" + (enabled ? "" : "X")
                    + scope + ":" + getDescription();
            }
            if (!enabled || !"a".equals(scope)) {
                return name + ":" + (enabled ? "" : "X") + scope;
            }
            return name;
        }
    }

    
Separates packages on the overview page into whatever
groups you specify, one group per table.
Returns:
a group argument to be configured/**
     * Separates packages on the overview page into whatever
     * groups you specify, one group per table.
     * @return a group argument to be configured
     */
    public GroupArgument createGroup() {
        final GroupArgument ga = new GroupArgument();
        groups.add(ga);
        return ga;
    }

    
A class corresponding to the group nested element.
/**
     * A class corresponding to the group nested element.
     */
    public class GroupArgument {
        private Html title;
        private final List<PackageName> packages = new Vector<>();

        
Set the title attribute using a string.
Params:
src – a String value/**
         * Set the title attribute using a string.
         * @param src a <code>String</code> value
         */
        public void setTitle(final String src) {
            final Html h = new Html();
            h.addText(src);
            addTitle(h);
        }

        
Set the title attribute using a nested Html value.
Params:
text – a Html value/**
         * Set the title attribute using a nested Html value.
         * @param text a <code>Html</code> value
         */
        public void addTitle(final Html text) {
            title = text;
        }

        
Get the title.
Returns:
the title/**
         * Get the title.
         * @return the title
         */
        public String getTitle() {
            return title != null ? title.getText() : null;
        }

        
Set the packages to Javadoc on.
Params:
src – a comma separated list of packages/**
         * Set the packages to Javadoc on.
         * @param src a comma separated list of packages
         */
        public void setPackages(final String src) {
            final StringTokenizer tok = new StringTokenizer(src, ",");
            while (tok.hasMoreTokens()) {
                final String p = tok.nextToken();
                final PackageName pn = new PackageName();
                pn.setName(p);
                addPackage(pn);
            }
        }

        
Add a package nested element.
Params:
pn – a nested element specifying the package./**
         * Add a package nested element.
         * @param pn a nested element specifying the package.
         */
        public void addPackage(final PackageName pn) {
            packages.add(pn);
        }

        
Get the packages as a colon separated list.
Returns:
the packages as a string/**
         * Get the packages as a colon separated list.
         * @return the packages as a string
         */
        public String getPackages() {
            return packages.stream().map(Object::toString)
                .collect(Collectors.joining(":"));
        }
    }

    
Charset for cross-platform viewing of generated documentation.
Params:
src – the name of the charset/**
     * Charset for cross-platform viewing of generated documentation.
     * @param src the name of the charset
     */
    public void setCharset(final String src) {
        this.addArgIfNotEmpty("-charset", src);
    }

    
Should the build process fail if Javadoc fails (as indicated by
a non zero return code)?
Default is false.
Params:
b – a boolean value/**
     * Should the build process fail if Javadoc fails (as indicated by
     * a non zero return code)?
     *
     * <p>Default is false.</p>
     * @param b a <code>boolean</code> value
     */
    public void setFailonerror(final boolean b) {
        failOnError = b;
    }

    
Should the build process fail if Javadoc warns (as indicated by
the word "warning" on stdout)?
Default is false.
Params:
b – a boolean value
Since:
Ant 1.9.4/**
     * Should the build process fail if Javadoc warns (as indicated by
     * the word "warning" on stdout)?
     *
     * <p>Default is false.</p>
     * @param b a <code>boolean</code> value
     * @since Ant 1.9.4
     */
    public void setFailonwarning(final boolean b) {
        failOnWarning = b;
    }

    
Enables the -source switch, will be ignored if Javadoc is not
the 1.4 version.
Params:
source – a String value
Since:
Ant 1.5/**
     * Enables the -source switch, will be ignored if Javadoc is not
     * the 1.4 version.
     * @param source a <code>String</code> value
     * @since Ant 1.5
     */
    public void setSource(final String source) {
        this.source = source;
    }

    
Sets the actual executable command to invoke, instead of the binary
javadoc found in Ant's JDK.
Params:
executable – the command to invoke.
Since:
Ant 1.6.3/**
     * Sets the actual executable command to invoke, instead of the binary
     * <code>javadoc</code> found in Ant's JDK.
     * @param executable the command to invoke.
     * @since Ant 1.6.3
     */
    public void setExecutable(final String executable) {
        this.executable = executable;
    }

    
Adds a packageset.
All included directories will be translated into package
names be converting the directory separator into dots.
Params:
packageSet – a directory set
Since:
1.5/**
     * Adds a packageset.
     *
     * <p>All included directories will be translated into package
     * names be converting the directory separator into dots.</p>
     * @param packageSet a directory set
     * @since 1.5
     */
    public void addPackageset(final DirSet packageSet) {
        packageSets.add(packageSet);
    }

    
Adds a fileset.
All included files will be added as sourcefiles.  The task
will automatically add
includes="**/*.java" to the
fileset.
Params:
fs – a file set
Since:
1.5/**
     * Adds a fileset.
     *
     * <p>All included files will be added as sourcefiles.  The task
     * will automatically add
     * <code>includes=&quot;**&#47;*.java&quot;</code> to the
     * fileset.</p>
     * @param fs a file set
     * @since 1.5
     */
    public void addFileset(final FileSet fs) {
        createSourceFiles().add(fs);
    }

    
Adds a container for resource collections.
All included files will be added as sourcefiles.
Returns:
the source files to configure.
Since:
1.7/**
     * Adds a container for resource collections.
     *
     * <p>All included files will be added as sourcefiles.</p>
     * @return the source files to configure.
     * @since 1.7
     */
    public ResourceCollectionContainer createSourceFiles() {
        return nestedSourceFiles;
    }

    
Enables the -linksource switch, will be ignored if Javadoc is not
the 1.4 version. Default is false
Params:
b – a String value
Since:
Ant 1.6/**
     * Enables the -linksource switch, will be ignored if Javadoc is not
     * the 1.4 version. Default is false
     * @param b a <code>String</code> value
     * @since Ant 1.6
     */
    public void setLinksource(final boolean b) {
        this.linksource = b;
    }

    
Enables the -linksource switch, will be ignored if Javadoc is not
the 1.4 version. Default is false
Params:
b – a String value
Since:
Ant 1.6/**
     * Enables the -linksource switch, will be ignored if Javadoc is not
     * the 1.4 version. Default is false
     * @param b a <code>String</code> value
     * @since Ant 1.6
     */
    public void setBreakiterator(final boolean b) {
        this.breakiterator = b;
    }

    
Enables the -noqualifier switch, will be ignored if Javadoc is not
the 1.4 version.
Params:
noqualifier – the parameter to the -noqualifier switch
Since:
Ant 1.6/**
     * Enables the -noqualifier switch, will be ignored if Javadoc is not
     * the 1.4 version.
     * @param noqualifier the parameter to the -noqualifier switch
     * @since Ant 1.6
     */
    public void setNoqualifier(final String noqualifier) {
        this.noqualifier = noqualifier;
    }

    
If set to true, Ant will also accept packages that only hold
package.html files but no Java sources.
Params:
b – a boolean value.
Since:
Ant 1.6.3/**
     * If set to true, Ant will also accept packages that only hold
     * package.html files but no Java sources.
     * @param b a <code>boolean</code> value.
     * @since Ant 1.6.3
     */
    public void setIncludeNoSourcePackages(final boolean b) {
        this.includeNoSourcePackages = b;
    }

    
Enables deep-copying of doc-files directories.
Params:
b – boolean
Since:
Ant 1.8.0/**
     * Enables deep-copying of <code>doc-files</code> directories.
     *
     * @param b boolean
     * @since Ant 1.8.0
     */
    public void setDocFilesSubDirs(final boolean b) {
        docFilesSubDirs = b;
    }

    
Colon-separated list of doc-files subdirectories to skip if docFilesSubDirs is true. 
Params:
s – String
Since:
Ant 1.8.0/**
     * Colon-separated list of <code>doc-files</code> subdirectories
     * to skip if {@link #setDocFilesSubDirs docFilesSubDirs is true}.
     *
     * @param s String
     * @since Ant 1.8.0
     */
    public void setExcludeDocFilesSubDir(final String s) {
        excludeDocFilesSubDir = s;
    }

    
Whether to post-process the generated javadocs in order to mitigate CVE-2013-1571.
Params:
b – boolean
Since:
Ant 1.9.2/**
     * Whether to post-process the generated javadocs in order to mitigate CVE-2013-1571.
     *
     * @param b boolean
     * @since Ant 1.9.2
     */
    public void setPostProcessGeneratedJavadocs(final boolean b) {
        postProcessGeneratedJavadocs = b;
    }

    
Execute the task.
Throws:
BuildException – on error/**
     * Execute the task.
     * @throws BuildException on error
     */
    @Override
    public void execute() throws BuildException {
        checkTaskName();

        final List<String> packagesToDoc = new Vector<>();
        final Path sourceDirs = new Path(getProject());

        checkPackageAndSourcePath();

        if (sourcePath != null) {
            sourceDirs.addExisting(sourcePath);
        }

        parsePackages(packagesToDoc, sourceDirs);
        checkPackages(packagesToDoc, sourceDirs);

        final List<SourceFile> sourceFilesToDoc = new ArrayList<>(sourceFiles);
        addSourceFiles(sourceFilesToDoc);

        checkPackagesToDoc(packagesToDoc, sourceFilesToDoc);

        log("Generating Javadoc", Project.MSG_INFO);

        final Commandline toExecute = (Commandline) cmd.clone();
        if (executable != null) {
            toExecute.setExecutable(executable);
        } else {
            toExecute.setExecutable(JavaEnvUtils.getJdkExecutable("javadoc"));
        }

        //  Javadoc arguments
        generalJavadocArguments(toExecute);  // general Javadoc arguments
        doSourcePath(toExecute, sourceDirs); // sourcepath
        doDoclet(toExecute);   // arguments for default doclet
        doBootPath(toExecute); // bootpath
        doLinks(toExecute);    // links arguments
        doGroup(toExecute);    // group attribute
        doGroups(toExecute);  // groups attribute
        doDocFilesSubDirs(toExecute); // docfilessubdir attribute
        doModuleArguments(toExecute);

        doTags(toExecute);
        doSource(toExecute);
        doLinkSource(toExecute);
        doNoqualifier(toExecute);
		
        if (breakiterator) {
            toExecute.createArgument().setValue("-breakiterator");
        }
        // If using an external file, write the command line options to it
        if (useExternalFile) {
            writeExternalArgs(toExecute);
        }

        File tmpList = null;
        FileWriter wr = null;
        try {
            /**
             * Write sourcefiles and package names to a temporary file
             * if requested.
             */
            BufferedWriter srcListWriter = null;
            if (useExternalFile) {
                tmpList = FILE_UTILS.createTempFile("javadoc", "", null, true, true);
                toExecute.createArgument()
                    .setValue("@" + tmpList.getAbsolutePath());
                wr = new FileWriter(tmpList.getAbsolutePath(), true);
                srcListWriter = new BufferedWriter(wr);
            }

            doSourceAndPackageNames(
                toExecute, packagesToDoc, sourceFilesToDoc,
                useExternalFile, tmpList, srcListWriter);

            if (useExternalFile) {
                srcListWriter.flush(); //NOSONAR
            }
        } catch (final IOException e) {
            if (tmpList != null) {
                tmpList.delete();
            }
            throw new BuildException("Error creating temporary file",
                                     e, getLocation());
        } finally {
            FileUtils.close(wr);
        }

        if (packageList != null) {
            toExecute.createArgument().setValue("@" + packageList);
        }
        log(toExecute.describeCommand(), Project.MSG_VERBOSE);

        log("Javadoc execution", Project.MSG_INFO);

        final JavadocOutputStream out = new JavadocOutputStream(Project.MSG_INFO);
        final JavadocOutputStream err = new JavadocOutputStream(Project.MSG_WARN);
        final Execute exe = new Execute(new PumpStreamHandler(out, err));
        exe.setAntRun(getProject());

        /*
         * No reason to change the working directory as all filenames and
         * path components have been resolved already.
         *
         * Avoid problems with command line length in some environments.
         */
        exe.setWorkingDirectory(null);
        try {
            exe.setCommandline(toExecute.getCommandline());
            final int ret = exe.execute();
            if (ret != 0 && failOnError) {
                throw new BuildException("Javadoc returned " + ret,
                                         getLocation());
            }
            if (out.sawWarnings() && failOnWarning) {
                throw new BuildException("Javadoc issued warnings.",
                                         getLocation());
            }
            postProcessGeneratedJavadocs();
        } catch (final IOException e) {
            throw new BuildException("Javadoc failed: " + e, e, getLocation());
        } finally {
            if (tmpList != null) {
                tmpList.delete();
                tmpList = null;
            }

            out.logFlush();
            err.logFlush();
            FileUtils.close(out);
            FileUtils.close(err);
        }
    }

    private void checkTaskName() {
        if ("javadoc2".equals(getTaskType())) {
            log("Warning: the task name <javadoc2> is deprecated."
                + " Use <javadoc> instead.",
                Project.MSG_WARN);
        }
    }

    private void checkPackageAndSourcePath() {
        if (packageList != null && sourcePath == null) {
            final String msg = "sourcePath attribute must be set when "
                + "specifying packagelist.";
            throw new BuildException(msg);
        }
    }

    private void checkPackages(final List<String> packagesToDoc, final Path sourceDirs) {
        if (!packagesToDoc.isEmpty() && sourceDirs.isEmpty()) {
            throw new BuildException(
                "sourcePath attribute must be set when specifying package names.");
        }
    }

    private void checkPackagesToDoc(
        final List<String> packagesToDoc, final List<SourceFile> sourceFilesToDoc) {
        if (packageList == null && packagesToDoc.isEmpty()
            && sourceFilesToDoc.isEmpty() && moduleNames.isEmpty()) {
            throw new BuildException("No source files, no packages and no modules have "
                                     + "been specified.");
        }
    }

    private void doSourcePath(final Commandline toExecute, final Path sourceDirs) {
        if (!sourceDirs.isEmpty()) {
            toExecute.createArgument().setValue("-sourcepath");
            toExecute.createArgument().setPath(sourceDirs);
        }
    }

    private void generalJavadocArguments(final Commandline toExecute) {
        if (doctitle != null) {
            toExecute.createArgument().setValue("-doctitle");
            toExecute.createArgument().setValue(expand(doctitle.getText()));
        }
        if (header != null) {
            toExecute.createArgument().setValue("-header");
            toExecute.createArgument().setValue(expand(header.getText()));
        }
        if (footer != null) {
            toExecute.createArgument().setValue("-footer");
            toExecute.createArgument().setValue(expand(footer.getText()));
        }
        if (bottom != null) {
            toExecute.createArgument().setValue("-bottom");
            toExecute.createArgument().setValue(expand(bottom.getText()));
        }

        if (classpath == null) {
            classpath = new Path(getProject()).concatSystemClasspath("last");
        } else {
            classpath = classpath.concatSystemClasspath("ignore");
        }

        if (classpath.size() > 0) {
            toExecute.createArgument().setValue("-classpath");
            toExecute.createArgument().setPath(classpath);
        }

        if (version && doclet == null) {
            toExecute.createArgument().setValue("-version");
        }
        if (author && doclet == null) {
            toExecute.createArgument().setValue("-author");
        }

        if (doclet == null && destDir == null) {
            throw new BuildException("destdir attribute must be set!");
        }
    }

    private void doDoclet(final Commandline toExecute) {
        if (doclet != null) {
            if (doclet.getName() == null) {
                throw new BuildException("The doclet name must be specified.", getLocation());
            }
            toExecute.createArgument().setValue("-doclet");
            toExecute.createArgument().setValue(doclet.getName());
            if (doclet.getPath() != null) {
                final Path docletPath = doclet.getPath().concatSystemClasspath("ignore");
                if (docletPath.size() != 0) {
                    toExecute.createArgument().setValue("-docletpath");
                    toExecute.createArgument().setPath(docletPath);
                }
            }
            for (final DocletParam param : Collections.list(doclet.getParams())) {
                if (param.getName() == null) {
                    throw new BuildException("Doclet parameters must have a name");
                }
                toExecute.createArgument().setValue(param.getName());
                if (param.getValue() != null) {
                    toExecute.createArgument().setValue(param.getValue());
                }
            }
        }
    }

    private void writeExternalArgs(final Commandline toExecute) {
        // If using an external file, write the command line options to it
        File optionsTmpFile = null;
        try {
            optionsTmpFile = FILE_UTILS.createTempFile(
                "javadocOptions", "", null, true, true);
            final String[] listOpt = toExecute.getArguments();
            toExecute.clearArgs();
            toExecute.createArgument().setValue(
                "@" + optionsTmpFile.getAbsolutePath());
            try (BufferedWriter optionsListWriter = new BufferedWriter(
                new FileWriter(optionsTmpFile.getAbsolutePath(), true))) {
                for (final String opt : listOpt) {
                    if (opt.startsWith("-J-")) {
                        toExecute.createArgument().setValue(opt);
                    } else if (opt.startsWith("-")) {
                        optionsListWriter.write(opt);
                        optionsListWriter.write(" ");
                    } else {
                        optionsListWriter.write(quoteString(opt));
                        optionsListWriter.newLine();
                    }
                }
            }
        } catch (final IOException ex) {
            if (optionsTmpFile != null) {
                optionsTmpFile.delete();
            }
            throw new BuildException(
                "Error creating or writing temporary file for javadoc options",
                ex, getLocation());
        }
    }

    private void doBootPath(final Commandline toExecute) {
        Path bcp = new Path(getProject());
        if (bootclasspath != null) {
            bcp.append(bootclasspath);
        }
        bcp = bcp.concatSystemBootClasspath("ignore");
        if (bcp.size() > 0) {
            toExecute.createArgument().setValue("-bootclasspath");
            toExecute.createArgument().setPath(bcp);
        }
    }

    private void doLinks(final Commandline toExecute) {
        for (final LinkArgument la : links) {
            if (la.getHref() == null || la.getHref().isEmpty()) {
                log("No href was given for the link - skipping",
                    Project.MSG_VERBOSE);
                continue;
            }
            String link = null;
            if (la.shouldResolveLink()) {
                final File hrefAsFile =
                    getProject().resolveFile(la.getHref());
                if (hrefAsFile.exists()) {
                    try {
                        link = FILE_UTILS.getFileURL(hrefAsFile)
                            .toExternalForm();
                    } catch (final MalformedURLException ex) {
                        // should be impossible
                        log("Warning: link location was invalid "
                            + hrefAsFile, Project.MSG_WARN);
                    }
                }
            }
            if (link == null) {
                // is the href a valid URL
                try {
                    final URL base = new URL("file://.");
                    // created for the side effect of throwing a MalformedURLException
                    new URL(base, la.getHref()); //NOSONAR
                    link = la.getHref();
                } catch (final MalformedURLException mue) {
                    // ok - just skip
                    log("Link href \"" + la.getHref()
                        + "\" is not a valid url - skipping link",
                        Project.MSG_WARN);
                    continue;
                }
            }

            if (la.isLinkOffline()) {
                final File packageListLocation = la.getPackagelistLoc();
                URL packageListURL = la.getPackagelistURL();
                if (packageListLocation == null
                    && packageListURL == null) {
                    throw new BuildException(
                        "The package list location for link " + la.getHref()
                            + " must be provided because the link is offline");
                }
                if (packageListLocation != null) {
                    final File packageListFile =
                        new File(packageListLocation, "package-list");
                    if (packageListFile.exists()) {
                        try {
                            packageListURL =
                                FILE_UTILS.getFileURL(packageListLocation);
                        } catch (final MalformedURLException ex) {
                            log("Warning: Package list location was "
                                + "invalid " + packageListLocation,
                                Project.MSG_WARN);
                        }
                    } else {
                        log("Warning: No package list was found at "
                            + packageListLocation, Project.MSG_VERBOSE);
                    }
                }
                if (packageListURL != null) {
                    toExecute.createArgument().setValue("-linkoffline");
                    toExecute.createArgument().setValue(link);
                    toExecute.createArgument()
                        .setValue(packageListURL.toExternalForm());
                }
            } else {
                toExecute.createArgument().setValue("-link");
                toExecute.createArgument().setValue(link);
            }
        }
    }

    private void doGroup(final Commandline toExecute) {
        // add the single group arguments
        // Javadoc 1.2 rules:
        //   Multiple -group args allowed.
        //   Each arg includes 3 strings: -group [name] [packagelist].
        //   Elements in [packagelist] are colon-delimited.
        //   An element in [packagelist] may end with the * wildcard.

        // Ant javadoc task rules for group attribute:
        //   Args are comma-delimited.
        //   Each arg is 2 space-delimited strings.
        //   E.g., group="XSLT_Packages org.apache.xalan.xslt*,
        //                XPath_Packages org.apache.xalan.xpath*"
        if (group != null) {
            final StringTokenizer tok = new StringTokenizer(group, ",", false);
            while (tok.hasMoreTokens()) {
                final String grp = tok.nextToken().trim();
                final int space = grp.indexOf(' ');
                if (space > 0) {
                    final String name = grp.substring(0, space);
                    final String pkgList = grp.substring(space + 1);
                    toExecute.createArgument().setValue("-group");
                    toExecute.createArgument().setValue(name);
                    toExecute.createArgument().setValue(pkgList);
                }
            }
        }
    }

    // add the group arguments
    private void doGroups(final Commandline toExecute) {
        for (final GroupArgument ga : groups) {
            final String title = ga.getTitle();
            final String packages = ga.getPackages();
            if (title == null || packages == null) {
                throw new BuildException(
                    "The title and packages must be specified for group elements.");
            }
            toExecute.createArgument().setValue("-group");
            toExecute.createArgument().setValue(expand(title));
            toExecute.createArgument().setValue(packages);
        }
    }

    private void doNoqualifier(final Commandline toExecute) {
        if (noqualifier != null && doclet == null) {
            toExecute.createArgument().setValue("-noqualifier");
            toExecute.createArgument().setValue(noqualifier);
        }
    }

    private void doLinkSource(final Commandline toExecute) {
        if (linksource && doclet == null) {
            toExecute.createArgument().setValue("-linksource");
        }
    }

    private void doSource(final Commandline toExecute) {
        final String sourceArg = source != null ? source : getProject().getProperty(MagicNames.BUILD_JAVAC_SOURCE);
        if (sourceArg != null) {
            toExecute.createArgument().setValue("-source");
            toExecute.createArgument().setValue(sourceArg);
        }
    }

    private void doTags(final Commandline toExecute) {
        for (final Object element : tags) {
            if (element instanceof TagArgument) {
                final TagArgument ta = (TagArgument) element;
                final File tagDir = ta.getDir(getProject());
                if (tagDir == null) {
                    // The tag element is not used as a fileset,
                    // but specifies the tag directly.
                    toExecute.createArgument().setValue("-tag");
                    toExecute.createArgument().setValue(ta.getParameter());
                } else {
                    // The tag element is used as a
                    // fileset. Parse all the files and create
                    // -tag arguments.
                    final DirectoryScanner tagDefScanner = ta.getDirectoryScanner(getProject());
                    for (String file : tagDefScanner.getIncludedFiles()) {
                        final File tagDefFile = new File(tagDir, file);
                        try (final BufferedReader in = new BufferedReader(new FileReader(tagDefFile))) {
                            in.lines().forEach(line -> {
                                toExecute.createArgument().setValue("-tag");
                                toExecute.createArgument().setValue(line);
                            });
                        } catch (final IOException ioe) {
                            throw new BuildException("Couldn't read tag file from " + tagDefFile.getAbsolutePath(),
                                    ioe);
                        }
                    }
                }
            } else {
                final ExtensionInfo tagletInfo = (ExtensionInfo) element;
                toExecute.createArgument().setValue("-taglet");
                toExecute.createArgument().setValue(tagletInfo.getName());
                if (tagletInfo.getPath() != null) {
                    final Path tagletPath = tagletInfo.getPath().concatSystemClasspath("ignore");
                    if (!tagletPath.isEmpty()) {
                        toExecute.createArgument().setValue("-tagletpath");
                        toExecute.createArgument().setPath(tagletPath);
                    }
                }
            }
        }
    }

    private void doDocFilesSubDirs(final Commandline toExecute) {
        if (docFilesSubDirs) {
            toExecute.createArgument().setValue("-docfilessubdirs");
            if (excludeDocFilesSubDir != null && !excludeDocFilesSubDir.trim().isEmpty()) {
                toExecute.createArgument().setValue("-excludedocfilessubdir");
                toExecute.createArgument().setValue(excludeDocFilesSubDir);
            }
        }
    }

    private void doSourceAndPackageNames(
        final Commandline toExecute,
        final List<String> packagesToDoc,
        final List<SourceFile> sourceFilesToDoc,
        final boolean useExternalFile,
        final File tmpList,
        final BufferedWriter srcListWriter)
        throws IOException {
        for (final String packageName : packagesToDoc) {
            if (useExternalFile) {
                srcListWriter.write(packageName);
                srcListWriter.newLine();
            } else {
                toExecute.createArgument().setValue(packageName);
            }
        }

        for (final SourceFile sf : sourceFilesToDoc) {
            final String sourceFileName = sf.getFile().getAbsolutePath();
            if (useExternalFile) {
                // TODO what is the following doing?
                //     should it run if !javadoc4 && executable != null?
                if (sourceFileName.contains(" ")) {
                    String name = sourceFileName;
                    if (File.separatorChar == '\\') {
                        name = sourceFileName.replace(File.separatorChar, '/');
                    }
                    srcListWriter.write("\"" + name + "\"");
                } else {
                    srcListWriter.write(sourceFileName);
                }
                srcListWriter.newLine();
            } else {
                toExecute.createArgument().setValue(sourceFileName);
            }
        }
    }

    
Quote a string to place in a @ file.
Params:
str – the string to quote
Returns:
the quoted string, if there is no need to quote the string,
        return the original string./**
     * Quote a string to place in a @ file.
     * @param str the string to quote
     * @return the quoted string, if there is no need to quote the string,
     *         return the original string.
     */
    private String quoteString(final String str) {
        if (!containsWhitespace(str)
            && !str.contains("'") && !str.contains("\"")) {
            return str;
        }
        if (!str.contains("'")) {
            return quoteString(str, '\'');
        }
        return quoteString(str, '"');
    }

    private boolean containsWhitespace(final String s) {
        for (char c : s.toCharArray()) {
            if (Character.isWhitespace(c)) {
                return true;
            }
        }
        return false;
    }

    private String quoteString(final String str, final char delim) {
        final StringBuilder buf = new StringBuilder(str.length() * 2);
        buf.append(delim);
        boolean lastCharWasCR = false;
        for (final char c : str.toCharArray()) {
            if (c == delim) { // can't put the non-constant delim into a case
                buf.append('\\').append(c);
                lastCharWasCR = false;
            } else {
                switch (c) {
                case '\\':
                    buf.append("\\\\");
                    lastCharWasCR = false;
                    break;
                case '\r':
                    // insert a line continuation marker
                    buf.append("\\\r");
                    lastCharWasCR = true;
                    break;
                case '\n':
                    // insert a line continuation marker unless this
                    // is a \r\n sequence in which case \r already has
                    // created the marker
                    if (!lastCharWasCR) {
                        buf.append("\\\n");
                    } else {
                        buf.append("\n");
                    }
                    lastCharWasCR = false;
                    break;
                default:
                    buf.append(c);
                    lastCharWasCR = false;
                    break;
                }
            }
        }
        buf.append(delim);
        return buf.toString();
    }

    
Add the files matched by the nested source files to the Vector
as SourceFile instances.
Since:
1.7/**
     * Add the files matched by the nested source files to the Vector
     * as SourceFile instances.
     *
     * @since 1.7
     */
    private void addSourceFiles(final List<SourceFile> sf) {
        for (ResourceCollection rc : nestedSourceFiles) {
            if (!rc.isFilesystemOnly()) {
                throw new BuildException(
                    "only file system based resources are supported by javadoc");
            }
            if (rc instanceof FileSet) {
                final FileSet fs = (FileSet) rc;
                if (!fs.hasPatterns() && !fs.hasSelectors()) {
                    final FileSet fs2 = (FileSet) fs.clone();
                    fs2.createInclude().setName("**/*.java");
                    if (includeNoSourcePackages) {
                        fs2.createInclude().setName("**/package.html");
                    }
                    rc = fs2;
                }
            }
            for (final Resource r : rc) {
                sf.add(new SourceFile(r.as(FileProvider.class).getFile()));
            }
        }
    }

    
Add the directories matched by the nested dirsets to the Vector
and the base directories of the dirsets to the Path.  It also
handles the packages and excludepackages attributes and
elements.
Since:
1.5/**
     * Add the directories matched by the nested dirsets to the Vector
     * and the base directories of the dirsets to the Path.  It also
     * handles the packages and excludepackages attributes and
     * elements.
     *
     * @since 1.5
     */
    private void parsePackages(final List<String> pn, final Path sp) {
        final Set<String> addedPackages = new HashSet<>();
        final List<DirSet> dirSets = new ArrayList<>(packageSets);

        // for each sourcePath entry, add a directoryset with includes
        // taken from packagenames attribute and nested package
        // elements and excludes taken from excludepackages attribute
        // and nested excludepackage elements
        if (sourcePath != null) {
            final PatternSet ps = new PatternSet();
            ps.setProject(getProject());
            if (packageNames.isEmpty()) {
                ps.createInclude().setName("**");
            } else {
                packageNames.stream().map(PackageName::getName)
                    .map(s -> s.replace('.', '/').replaceFirst("\\*$", "**"))
                    .forEach(pkg -> ps.createInclude().setName(pkg));
            }

            excludePackageNames.stream().map(PackageName::getName)
                .map(s -> s.replace('.', '/').replaceFirst("\\*$", "**"))
                .forEach(pkg -> ps.createExclude().setName(pkg));

            for (String pathElement : sourcePath.list()) {
                final File dir = new File(pathElement);
                if (dir.isDirectory()) {
                    final DirSet ds = new DirSet();
                    ds.setProject(getProject());
                    ds.setDefaultexcludes(useDefaultExcludes);
                    ds.setDir(dir);
                    ds.createPatternSet().addConfiguredPatternset(ps);
                    dirSets.add(ds);
                } else {
                    log("Skipping " + pathElement
                        + " since it is no directory.", Project.MSG_WARN);
                }
            }
        }

        for (DirSet ds : dirSets) {
            final File baseDir = ds.getDir(getProject());
            log("scanning " + baseDir + " for packages.", Project.MSG_DEBUG);
            final DirectoryScanner dsc = ds.getDirectoryScanner(getProject());
            boolean containsPackages = false;
            for (String dir : dsc.getIncludedDirectories()) {
                // are there any java files in this directory?
                final File pd = new File(baseDir, dir);
                final String[] files = pd.list((directory,
                    name) -> name.endsWith(".java") || (includeNoSourcePackages
                        && name.equals("package.html")));

                if (files.length > 0) {
                    if (dir.isEmpty()) {
                        log(baseDir
                            + " contains source files in the default package, you must specify them as source files not packages.",
                            Project.MSG_WARN);
                    } else {
                        containsPackages = true;
                        final String packageName =
                                dir.replace(File.separatorChar, '.');
                        if (!addedPackages.contains(packageName)) {
                            addedPackages.add(packageName);
                            pn.add(packageName);
                        }
                    }
                }
            }
            if (containsPackages) {
                // We don't need to care for duplicates here,
                // Path.list does it for us.
                sp.createPathElement().setLocation(baseDir);
            } else {
                log(baseDir + " doesn\'t contain any packages, dropping it.",
                    Project.MSG_VERBOSE);
            }
        }
    }

    private void postProcessGeneratedJavadocs() throws IOException {
        if (!postProcessGeneratedJavadocs) {
            return;
        }
        if (destDir != null && !destDir.isDirectory()) {
            log("No javadoc created, no need to post-process anything",
                Project.MSG_VERBOSE);
            return;
        }
        final InputStream in = Javadoc.class
            .getResourceAsStream("javadoc-frame-injections-fix.txt");
        if (in == null) {
            throw new FileNotFoundException(
                "Missing resource 'javadoc-frame-injections-fix.txt' in classpath.");
        }
        final String fixData;
        try {
            fixData =
                fixLineFeeds(FileUtils
                             .readFully(new InputStreamReader(in, StandardCharsets.US_ASCII)))
                .trim();
        } finally {
            FileUtils.close(in);
        }

        final DirectoryScanner ds = new DirectoryScanner();
        ds.setBasedir(destDir);
        ds.setCaseSensitive(false);
        ds.setIncludes(new String[] {
                "**/index.html", "**/index.htm", "**/toc.html", "**/toc.htm"
            });
        ds.addDefaultExcludes();
        ds.scan();
        int patched = 0;
        for (final String f : ds.getIncludedFiles()) {
            patched += postProcess(new File(destDir, f), fixData);
        }
        if (patched > 0) {
            log("Patched " + patched + " link injection vulnerable javadocs",
                Project.MSG_INFO);
        }
    }

    private int postProcess(final File file, final String fixData) throws IOException {
        final String enc = docEncoding != null ? docEncoding
            : FILE_UTILS.getDefaultEncoding();
        // we load the whole file as one String (toc/index files are
        // generally small, because they only contain frameset declaration):
        String fileContents;
        try (InputStreamReader reader =
            new InputStreamReader(Files.newInputStream(file.toPath()), enc)) {
            fileContents = fixLineFeeds(FileUtils.safeReadFully(reader));
        }

        // check if file may be vulnerable because it was not
        // patched with "validURL(url)":
        if (!fileContents.contains("function validURL(url) {")) {
            // we need to patch the file!
            final String patchedFileContents = patchContent(fileContents, fixData);
            if (!patchedFileContents.equals(fileContents)) {
                try (final OutputStreamWriter w =
                    new OutputStreamWriter(Files.newOutputStream(file.toPath()), enc)) {
                    w.write(patchedFileContents);
                    w.close();
                    return 1;
                }
            }
        }
        return 0;
    }

    private String fixLineFeeds(final String orig) {
        return orig.replace("\r\n", "\n")
            .replace("\n", System.lineSeparator());
    }

    private String patchContent(final String fileContents, final String fixData) {
        // using regexes here looks like overkill
        final int start = fileContents.indexOf(LOAD_FRAME);
        if (start >= 0) {
            return fileContents.substring(0, start) + fixData
                + fileContents.substring(start + LOAD_FRAME_LEN);
        }
        return fileContents;
    }

    private void doModuleArguments(Commandline toExecute) {
        if (!moduleNames.isEmpty()) {
            toExecute.createArgument().setValue("--module");
            toExecute.createArgument()
                .setValue(moduleNames.stream().map(PackageName::getName)
                          .collect(Collectors.joining(",")));
        }
        if (modulePath != null) {
            toExecute.createArgument().setValue("--module-path");
            toExecute.createArgument().setPath(modulePath);
        }
        if (moduleSourcePath != null) {
            toExecute.createArgument().setValue("--module-source-path");
            toExecute.createArgument().setPath(moduleSourcePath);
        }
    }

    private class JavadocOutputStream extends LogOutputStream {
        JavadocOutputStream(final int level) {
            super(Javadoc.this, level);
        }

        //
        // Override the logging of output in order to filter out Generating
        // messages.  Generating messages are set to a priority of VERBOSE
        // unless they appear after what could be an informational message.
        //
        private String queuedLine = null;
        private boolean sawWarnings = false;

        @Override
        protected void processLine(final String line, final int messageLevel) {
            if (line.contains("warning")) {
                sawWarnings = true;
            }
            if (messageLevel == Project.MSG_INFO
                && line.startsWith("Generating ")) {
                if (queuedLine != null) {
                    super.processLine(queuedLine, Project.MSG_VERBOSE);
                }
                queuedLine = line;
            } else {
                if (queuedLine != null) {
                    if (line.startsWith("Building ")) {
                        super.processLine(queuedLine, Project.MSG_VERBOSE);
                    } else {
                        super.processLine(queuedLine, Project.MSG_INFO);
                    }
                    queuedLine = null;
                }
                super.processLine(line, messageLevel);
            }
        }

        protected void logFlush() {
            if (queuedLine != null) {
                super.processLine(queuedLine, Project.MSG_VERBOSE);
                queuedLine = null;
            }
        }

        public boolean sawWarnings() {
            return sawWarnings;
        }
    }

    
Convenience method to expand properties.
Params:
content – the string to expand
Returns:
the converted string/**
     * Convenience method to expand properties.
     * @param content the string to expand
     * @return the converted string
     */
    protected String expand(final String content) {
        return getProject().replaceProperties(content);
    }

}