Package org.apache.tools.ant.taskdefs
Class Javadoc
java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.Javadoc
- All Implemented Interfaces:
Cloneable
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
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
EnumeratedAttribute implementation supporting the Javadoc scoping values.class
This class stores info about doclets.class
Inner class used to manage doclet parameters.static class
A project aware class used for Javadoc extensions which take a name and a path such as doclet and taglet arguments.class
A class corresponding to the group nested element.static class
An HTML element in the Javadoc.class
Represents a link triplet (href, whether link is offline, location of the package list if off line)static class
Used to track info about the packages to be javadoc'dclass
Holds a collection of ResourceCollections.static class
This class is used to manage the source files to be processed.class
Class representing a -tag argument. -
Field Summary
Fields inherited from class org.apache.tools.ant.ProjectComponent
description, location, project
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addBottom
(Javadoc.Html text) Set the text to be placed at the bottom of each output file.void
addDoctitle
(Javadoc.Html text) Add a document title to use for the overview page.void
Add a package to be excluded from the Javadoc run.void
addFileset
(FileSet fs) Adds a fileset.void
addFooter
(Javadoc.Html text) Set the footer text to be placed at the bottom of each output file.void
addHeader
(Javadoc.Html text) Set the header text to be placed at the top of each output file.void
Add a single module to be processed.void
Add a single package to be processed.void
addPackageset
(DirSet packageSet) Adds a packageset.void
Add a single source file.void
addTaglet
(Javadoc.ExtensionInfo tagletInfo) Add a tagletAdds a command-line argument.Create a Path to be configured with the boot classpathCreate a Path to be configured with the classpath to useCreate a doclet to be used in the documentation generation.Separates packages on the overview page into whatever groups you specify, one group per table.Create link to Javadoc output at the given URL.Create a path to be configured with the locations of the module files.Create a path to be configured with the locations of the module source files.Adds a container for resource collections.Create a path to be configured with the locations of the source files.Creates and adds a -tag argument.void
execute()
Execute the task.protected String
Convenience method to expand properties.void
Set the scope to be processed.void
setAdditionalparam
(String add) Set an additional parameter on the command linevoid
setAuthor
(boolean b) Include the author tag in the generated documentation.void
setBootclasspath
(Path path) Set the boot classpath to use.void
Adds a reference to a CLASSPATH defined elsewhere.void
Set the text to be placed at the bottom of each output file.void
setBreakiterator
(boolean b) Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version.void
setCharset
(String src) Charset for cross-platform viewing of generated documentation.void
setClasspath
(Path path) Set the classpath to be used for this Javadoc run.void
Adds a reference to a CLASSPATH defined elsewhere.void
setDefaultexcludes
(boolean useDefaultExcludes) Sets whether default exclusions should be used or not.void
setDestdir
(File dir) Set the directory where the Javadoc output will be generated.void
setDocencoding
(String enc) Output file encoding name.void
setDocFilesSubDirs
(boolean b) Enables deep-copying ofdoc-files
directories.void
Set the class that starts the doclet used in generating the documentation.void
setDocletPath
(Path docletPath) Set the classpath used to find the doclet class.void
Set the classpath used to find the doclet class by reference.void
setDoctitle
(String doctitle) Set the title of the generated overview page.void
setEncoding
(String enc) Set the encoding name of the source files,void
Colon-separated list ofdoc-files
subdirectories to skip ifdocFilesSubDirs is true
.void
setExcludePackageNames
(String packages) Set the list of packages to be excluded.void
setExecutable
(String executable) Sets the actual executable command to invoke, instead of the binaryjavadoc
found in Ant's JDK.void
setExtdirs
(String path) Deprecated.since 1.5.x.void
setExtdirs
(Path path) Set the location of the extensions directories.void
setFailonerror
(boolean b) Should the build process fail if Javadoc fails (as indicated by a non zero return code)?void
setFailonwarning
(boolean b) Should the build process fail if Javadoc warns (as indicated by the word "warning" on stdout)?void
Set the footer text to be placed at the bottom of each output file.void
Group specified packages together in overview page.void
Set the header text to be placed at the top of each output file.void
setHelpfile
(File f) Specifies the HTML help file to use.void
setIncludeNoSourcePackages
(boolean b) If set to true, Ant will also accept packages that only hold package.html files but no Java sources.void
Create links to Javadoc output at the given URL.void
setLinkoffline
(String src) Link to docs at "url" using package list at "url2" - separate the URLs by using a space character.void
setLinksource
(boolean b) Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version.void
Set the local to use in documentation generation.void
setMaxmemory
(String max) Set the maximum memory to be used by the javadoc processvoid
setModulenames
(String modules) Set the module names to be processed.void
setModulePath
(Path mp) Specify where to find modulesvoid
Adds a reference to a path defined elsewhere that defines the module path.void
Specify where to find sources for modulesvoid
Adds a reference to a path defined elsewhere that defines the module source path.void
setNodeprecated
(boolean b) Control deprecation informationvoid
setNodeprecatedlist
(boolean b) Control deprecated list generationvoid
setNohelp
(boolean b) Control generation of help link.void
setNoindex
(boolean b) Control generation of index.void
setNonavbar
(boolean b) Control generation of the navigation bar.void
setNoqualifier
(String noqualifier) Enables the -noqualifier switch, will be ignored if Javadoc is not the 1.4 version.void
setNotree
(boolean b) Control class tree generation.void
setOld
(boolean b) Indicate whether Javadoc should produce old style (JDK 1.1) documentation.void
setOverview
(File f) Specify the file containing the overview to be included in the generated documentation.void
setPackage
(boolean b) Indicate whether only package, protected and public classes and members are to be included in the scope processedvoid
setPackageList
(String src) The name of a file containing the packages to process.void
setPackagenames
(String packages) Set the package names to be processed.void
setPostProcessGeneratedJavadocs
(boolean b) Whether to post-process the generated javadocs in order to mitigate CVE-2013-1571.void
setPrivate
(boolean b) Indicate whether all classes and members are to be included in the scope processedvoid
setProtected
(boolean b) Indicate whether only protected and public classes and members are to be included in the scope processedvoid
setPublic
(boolean b) Indicate whether only public classes and members are to be included in the scope processedvoid
setSerialwarn
(boolean b) Control warnings about serial tag.void
Enables the -source switch, will be ignored if Javadoc is not the 1.4 version.void
setSourcefiles
(String src) Set the list of source files to process.void
setSourcepath
(Path src) Specify where to find source filevoid
Adds a reference to a CLASSPATH defined elsewhere.void
setSplitindex
(boolean b) Generate a split indexvoid
Specifies the CSS stylesheet file to use.void
setUse
(boolean b) Generate the "use" page for each package.void
setUseExternalFile
(boolean b) Work around command line length limit by using an external file for the sourcefiles.void
setVerbose
(boolean b) Run javadoc in verbose modevoid
setVersion
(boolean b) Include the version tag in the generated documentation.void
setWindowtitle
(String title) Set the title to be placed in the HTML <title> tag of the generated documentation.Methods inherited from class org.apache.tools.ant.Task
bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
Methods inherited from class org.apache.tools.ant.ProjectComponent
clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject
-
Constructor Details
-
Javadoc
public Javadoc()
-
-
Method Details
-
setUseExternalFile
public void setUseExternalFile(boolean b) Work around command line length limit by using an external file for the sourcefiles.- Parameters:
b
- true if an external file is to be used.
-
setDefaultexcludes
public void setDefaultexcludes(boolean useDefaultExcludes) Sets whether default exclusions should be used or not.- Parameters:
useDefaultExcludes
- "true"|"on"|"yes" when default exclusions should be used, "false"|"off"|"no" when they shouldn't be used.
-
setMaxmemory
Set the maximum memory to be used by the javadoc process- Parameters:
max
- a string indicating the maximum memory according to the JVM conventions (e.g. 128m is 128 Megabytes)
-
setAdditionalparam
Set an additional parameter on the command line- Parameters:
add
- the additional command line parameter for the javadoc task.
-
createArg
Adds a command-line argument.- Returns:
- a command-line argument to configure
- Since:
- Ant 1.6
-
setSourcepath
Specify where to find source file- Parameters:
src
- a Path instance containing the various source directories.
-
createSourcepath
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.
-
setSourcepathRef
Adds a reference to a CLASSPATH defined elsewhere.- Parameters:
r
- the reference containing the source path definition.
-
setModulePath
Specify where to find modules- Parameters:
mp
- a Path instance containing the modules.- Since:
- Ant 1.10.6
-
createModulePath
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
-
setModulePathref
Adds a reference to a path defined elsewhere that defines the module path.- Parameters:
r
- the reference containing the module path definition.- Since:
- Ant 1.10.6
-
setModuleSourcePath
Specify where to find sources for modules- Parameters:
mp
- a Path instance containing the sources for modules.- Since:
- Ant 1.10.6
-
createModuleSourcePath
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
-
setModuleSourcePathref
Adds a reference to a path defined elsewhere that defines the module source path.- Parameters:
r
- the reference containing the module source path definition.- Since:
- Ant 1.10.6
-
setDestdir
Set the directory where the Javadoc output will be generated.- Parameters:
dir
- the destination directory.
-
setSourcefiles
Set the list of source files to process.- Parameters:
src
- a comma separated list of source files.
-
addSource
Add a single source file.- Parameters:
sf
- the source file to be processed.
-
setPackagenames
Set the package names to be processed.- Parameters:
packages
- a comma separated list of packages specs (may be wildcarded).- See Also:
-
setModulenames
Set the module names to be processed.- Parameters:
modules
- a comma separated list of module names- Since:
- Ant 1.10.6
-
addPackage
Add a single package to be processed. If the package name ends with ".*" the Javadoc task will find and process all subpackages.- Parameters:
pn
- the package name, possibly wildcarded.
-
addModule
Add a single module to be processed.- Parameters:
mn
- the module name- Since:
- Ant 1.10.6
-
setExcludePackageNames
Set the list of packages to be excluded.- Parameters:
packages
- a comma separated list of packages to be excluded. This may not include wildcards.
-
addExcludePackage
Add a package to be excluded from the Javadoc run.- Parameters:
pn
- the name of the package (wildcards are not permitted).
-
setOverview
Specify the file containing the overview to be included in the generated documentation.- Parameters:
f
- the file containing the overview.
-
setPublic
public void setPublic(boolean b) Indicate whether only public classes and members are to be included in the scope processed- Parameters:
b
- true if scope is to be public.
-
setProtected
public void setProtected(boolean b) Indicate whether only protected and public classes and members are to be included in the scope processed- Parameters:
b
- true if scope is to be protected.
-
setPackage
public void setPackage(boolean b) Indicate whether only package, protected and public classes and members are to be included in the scope processed- Parameters:
b
- true if scope is to be package level.
-
setPrivate
public void setPrivate(boolean b) Indicate whether all classes and members are to be included in the scope processed- Parameters:
b
- true if scope is to be private level.
-
setAccess
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.- Parameters:
at
- the scope to be processed.
-
setDoclet
Set the class that starts the doclet used in generating the documentation.- Parameters:
docletName
- the name of the doclet class.
-
setDocletPath
Set the classpath used to find the doclet class.- Parameters:
docletPath
- the doclet classpath.
-
setDocletPathRef
Set the classpath used to find the doclet class by reference.- Parameters:
r
- the reference to the Path instance to use as the doclet classpath.
-
createDoclet
Create a doclet to be used in the documentation generation.- Returns:
- a new DocletInfo instance to be configured.
-
addTaglet
Add a taglet- Parameters:
tagletInfo
- information about the taglet.
-
setOld
public void setOld(boolean b) 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- Parameters:
b
- if true attempt to generate old style documentation.
-
setClasspath
Set the classpath to be used for this Javadoc run.- Parameters:
path
- an Ant Path object containing the compilation classpath.
-
createClasspath
Create a Path to be configured with the classpath to use- Returns:
- a new Path instance to be configured with the classpath.
-
setClasspathRef
Adds a reference to a CLASSPATH defined elsewhere.- Parameters:
r
- the reference to an instance defining the classpath.
-
setBootclasspath
Set the boot classpath to use.- Parameters:
path
- the boot classpath.
-
createBootclasspath
Create a Path to be configured with the boot classpath- Returns:
- a new Path instance to be configured with the boot classpath.
-
setBootClasspathRef
Adds a reference to a CLASSPATH defined elsewhere.- Parameters:
r
- the reference to an instance defining the bootclasspath.
-
setExtdirs
Deprecated.since 1.5.x. Use thesetExtdirs(Path)
version.Set the location of the extensions directories.- Parameters:
path
- the string version of the path.
-
setExtdirs
Set the location of the extensions directories.- Parameters:
path
- a path containing the extension directories.
-
setVerbose
public void setVerbose(boolean b) Run javadoc in verbose mode- Parameters:
b
- true if operation is to be verbose.
-
setLocale
Set the local to use in documentation generation.- Parameters:
locale
- the locale to use.
-
setEncoding
Set the encoding name of the source files,- Parameters:
enc
- the name of the encoding for the source files.
-
setVersion
public void setVersion(boolean b) Include the version tag in the generated documentation.- Parameters:
b
- true if the version tag should be included.
-
setUse
public void setUse(boolean b) Generate the "use" page for each package.- Parameters:
b
- true if the use page should be generated.
-
setAuthor
public void setAuthor(boolean b) Include the author tag in the generated documentation.- Parameters:
b
- true if the author tag should be included.
-
setSplitindex
public void setSplitindex(boolean b) Generate a split index- Parameters:
b
- true if the index should be split into a file per letter.
-
setWindowtitle
Set the title to be placed in the HTML <title> tag of the generated documentation.- Parameters:
title
- the window title to use.
-
setDoctitle
Set the title of the generated overview page.- Parameters:
doctitle
- the Document title.
-
addDoctitle
Add a document title to use for the overview page.- Parameters:
text
- the HTML element containing the document title.
-
setHeader
Set the header text to be placed at the top of each output file.- Parameters:
header
- the header text
-
addHeader
Set the header text to be placed at the top of each output file.- Parameters:
text
- the header text
-
setBottom
Set the text to be placed at the bottom of each output file.- Parameters:
bottom
- the bottom text.
-
addBottom
Set the text to be placed at the bottom of each output file.- Parameters:
text
- the bottom text.
-
setLinkoffline
Link to docs at "url" using package list at "url2" - separate the URLs by using a space character.- Parameters:
src
- the offline link specification (url and package list)
-
setGroup
Group specified packages together in overview page.- Parameters:
src
- the group packages - a command separated list of group specs, each one being a group name and package specification separated by a space.
-
setLink
Create links to Javadoc output at the given URL.- Parameters:
src
- the URL to link to
-
setNodeprecated
public void setNodeprecated(boolean b) Control deprecation information- Parameters:
b
- If true, do not include deprecated information.
-
setNodeprecatedlist
public void setNodeprecatedlist(boolean b) Control deprecated list generation- Parameters:
b
- if true, do not generate deprecated list.
-
setNotree
public void setNotree(boolean b) Control class tree generation.- Parameters:
b
- if true, do not generate class hierarchy.
-
setNoindex
public void setNoindex(boolean b) Control generation of index.- Parameters:
b
- if true, do not generate index.
-
setNohelp
public void setNohelp(boolean b) Control generation of help link.- Parameters:
b
- if true, do not generate help link
-
setSerialwarn
public void setSerialwarn(boolean b) Control warnings about serial tag.- Parameters:
b
- if true, generate warning about the serial tag.
-
setStylesheetfile
Specifies the CSS stylesheet file to use.- Parameters:
f
- the file with the CSS to use.
-
setHelpfile
Specifies the HTML help file to use.- Parameters:
f
- the file containing help content.
-
setDocencoding
Output file encoding name.- Parameters:
enc
- name of the encoding to use.
-
setPackageList
The name of a file containing the packages to process.- Parameters:
src
- the file containing the package list.
-
createLink
Create link to Javadoc output at the given URL.- Returns:
- link argument to configure
-
createTag
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
-
createGroup
Separates packages on the overview page into whatever groups you specify, one group per table.- Returns:
- a group argument to be configured
-
setCharset
Charset for cross-platform viewing of generated documentation.- Parameters:
src
- the name of the charset
-
setFailonerror
public void setFailonerror(boolean b) Should the build process fail if Javadoc fails (as indicated by a non zero return code)?Default is false.
- Parameters:
b
- aboolean
value
-
setFailonwarning
public void setFailonwarning(boolean b) Should the build process fail if Javadoc warns (as indicated by the word "warning" on stdout)?Default is false.
- Parameters:
b
- aboolean
value- Since:
- Ant 1.9.4
-
setSource
Enables the -source switch, will be ignored if Javadoc is not the 1.4 version.- Parameters:
source
- aString
value- Since:
- Ant 1.5
-
setExecutable
Sets the actual executable command to invoke, instead of the binaryjavadoc
found in Ant's JDK.- Parameters:
executable
- the command to invoke.- Since:
- Ant 1.6.3
-
addPackageset
Adds a packageset.All included directories will be translated into package names be converting the directory separator into dots.
- Parameters:
packageSet
- a directory set- Since:
- 1.5
-
addFileset
Adds a fileset.All included files will be added as sourcefiles. The task will automatically add
includes="**/*.java"
to the fileset.- Parameters:
fs
- a file set- Since:
- 1.5
-
createSourceFiles
Adds a container for resource collections.All included files will be added as sourcefiles.
- Returns:
- the source files to configure.
- Since:
- 1.7
-
setLinksource
public void setLinksource(boolean b) Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version. Default is false- Parameters:
b
- aString
value- Since:
- Ant 1.6
-
setBreakiterator
public void setBreakiterator(boolean b) Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version. Default is false- Parameters:
b
- aString
value- Since:
- Ant 1.6
-
setNoqualifier
Enables the -noqualifier switch, will be ignored if Javadoc is not the 1.4 version.- Parameters:
noqualifier
- the parameter to the -noqualifier switch- Since:
- Ant 1.6
-
setIncludeNoSourcePackages
public void setIncludeNoSourcePackages(boolean b) If set to true, Ant will also accept packages that only hold package.html files but no Java sources.- Parameters:
b
- aboolean
value.- Since:
- Ant 1.6.3
-
setDocFilesSubDirs
public void setDocFilesSubDirs(boolean b) Enables deep-copying ofdoc-files
directories.- Parameters:
b
- boolean- Since:
- Ant 1.8.0
-
setExcludeDocFilesSubDir
Colon-separated list ofdoc-files
subdirectories to skip ifdocFilesSubDirs is true
.- Parameters:
s
- String- Since:
- Ant 1.8.0
-
setPostProcessGeneratedJavadocs
public void setPostProcessGeneratedJavadocs(boolean b) Whether to post-process the generated javadocs in order to mitigate CVE-2013-1571.- Parameters:
b
- boolean- Since:
- Ant 1.9.2
-
execute
Execute the task.- Overrides:
execute
in classTask
- Throws:
BuildException
- on error
-
expand
-