Create API documentation using the javadoc
command.
Task package: | org.schmant.task.base |
Java package: | org.schmant.task.jdk.javadoc.ext |
Category: | Documentation tasks |
Since: | 0.5 |
EntityFS-aware? | No* |
Implements: | ActionTaskFactory |
See also: | ExtStandardDocletDecorator ExtPdfDocletDecorator |
Description:
Create API documentation using the javadoc
command launched in an
external process. This task requires at least one
ExtJavadocTaskDecorator to generate any output,
for instance an ExtStandardDocletDecorator or an ExtPdfDocletDecorator.
The following strategy is used for locating the javadoc
command
to use:
- Use the value of the javadocExecutable property, if set
- Use the file
bin/javadoc[.exe]
relative to the javaHome property, if set - Use the file
bin/javadoc[.exe]
relative to theJAVA_HOME
environment variable, if set - Search for
javadoc[.exe]
in the directories listed in thePATH
environment variable.
For more documentation on the different properties, see Java's
javadoc
tool documentation.
Required properties
Properties
arguments | top |
Arguments to the program. The arguments will be given to the program in the order that they are added.
- Setter method:
addArgument(String arg)
Add one program argument.parameters:arg
– The program argument, for instance-f out.txt
.- Setter method:
addArguments(Object o)
Add one program argument or an array or a collection of program arguments.parameters:o
– One program argument or an array or collection of program arguments (strings).- Setter method:
clearArguments()
Clear the list of program arguments.
bootClasspathEntries | top |
A list of entities that make up the boot classpath for the
javadoc
command. The boot class path is listed in the order that
entities are added to this property.
- Setter method:
addBootClasspathEntries(Object o)
Add one or several boot classpath entries.parameters:- Setter method:
addBootClasspathEntry(Object o)
Add one or several boot classpath entries.parameters:- Setter method:
clearBootClasspathEntries()
Clear the boot classpath.
breakIterator | top |
Use the sentence boundary detector from
BreakIterator
for English?
- Setter method:
setBreakIterator(boolean b)
parameters:b
– Use the break iterator?- Default value:
false
(use Javadoc's default sentence break detector).
classpathDecorators | top |
A collection of
PathDecorator:s that are used
to add entries to the classpath. The decorators are run in the order that they
are added to this property. Classpath decorator entries are added to the classpath after all entries added
manually to the classpathEntries
property.
- Setter method:
addClasspathDecorator(PathDecorator pd)
Add one classpath decorator to the end of the list.parameters:pd
– A classpath decorator.- Setter method:
addClasspathDecorators(Object o)
Add one or several classpath decorators.parameters:- Setter method:
clearClasspathDecorators()
Clear the list of classpath decorators.- See also:
- classpathEntries
classpathEntries | top |
Manually set classpath entries. An entry must be a Jar file or a class file directory.
- Setter method:
addClasspathEntries(Object o)
Add one or several classpath entries.parameters:o
– One or an array or collection of entries to add to the class path.
Interpreted byInterpretAsFileStrategy
.- Setter method:
addClasspathEntry(Object o)
Add one entry to the end of the class path.parameters:- Setter method:
clearClasspathEntries()
Clear the list of classpath entries.- See also:
- classpathDecorators
decorators (required) | top |
A collection of ExtJavadocTaskDecorator:s. At least one doclet decorator must be set to generate any output.
- Setter method:
addDecorator(ExtJavadocTaskDecorator d)
Add one decorator.parameters:d
– A decorator.- Setter method:
addDecorators(Object; o)
Add one or several decorators.parameters:- Setter method:
clearDecorators()
Clear the list of decorators.
encoding | top |
The name of the character encoding for output files.
- Setter method:
setEncoding(String s)
parameters:s
– The name of the encoding, for instanceiso-8859-1
.- Default value:
- Unset (the platform default encoder is used).
environmentVariables | top |
Environment variables for the program. By default, the variables set are added
to the environment of the Schmant script. See the
inheritEnvironmentVariables
property.
- Setter method:
addEnvironmentVariable(String name, String value)
parameters:name
– The environment variable name, for instancePATH
.value
– The value of the variable.- Setter method:
addEnvironmentVariables(Object o)
Add one or several environment variables.parameters:o
– A string or an array or collection of strings. Each string must have the formatNAME=VALUE
.- Setter method:
clearEnvironmentVariables()
Clear the collection of environment variables.- See also:
- inheritEnvironmentVariables
excludePackages | top |
This is used together with subPackages to exclude certain packages and their subpackages.
- Setter method:
addExcludePackage(String s)
Add one exclude package.parameters:s
– A package name. That package and its subpackages will be excluded from the documentation.- Setter method:
addExcludePackages(Object o)
Add one or several exclude packages.parameters:o
– One or an array or collection of package names (strings). The packages and their subpackages will be excluded from the documentation.- Setter method:
clearExcludePackages()
Clear the list of packages to exclude.- See also:
- subPackages
extDirectories | top |
A list of directories containing extension classes. The extension directories are given to Javadoc in the order that they are added to this property.
- Setter method:
addExtDirectories(Object o)
Add one or several extension directories.parameters:- Setter method:
addExtDirectory(Object o)
Add one extension directory.parameters:- Setter method:
clearExtDirectories()
Clear the list of extension directories.
failOnErrors | top |
If the program exits with an error (an exit code != 0), should the task fail? See also ErrorIgnoringTF.
- Setter method:
setFailOnErrors(boolean b)
parameters:b
– Should the task fail on errors?- Default value:
-
true
(fails on errors)
inheritEnvironmentVariables | top |
Should the environment variables of the Schmant script be inherited?
- Setter method:
setInheritEnvironmentVariables(boolean b)
parameters:b
– Should environment variables be inherited?- Default value:
true
(environment variables are inherited)- See also:
- environmentVariables
javadocExecutable | top |
The path to the javadoc[.exe]
command
- Setter method:
setJavadocExecutable(Object o)
parameters:- See also:
- javaHome
javaHome | top |
The location of the Java Runtime Environment or Java Development Kit to use
- Setter method:
setJavaHome(Object o)
parameters:- See also:
- javadocExecutable
jvmOptions | top |
Options to the JVM running the javadoc
command. The options are given to the JVM in the order that they were added.
- Setter method:
addJvmOption(String s)
Add one JVM option.parameters:s
– A JVM option.- Setter method:
addJvmOptions(Object o)
Add one or several JVM options.parameters:o
– One or an array or collection of JVM options (strings).- Setter method:
clearJvmOptions()
Clear the list of JVM options.
locale | top |
Set the locale used for generating the documentation.
- Setter method:
setLocale(String s)
parameters:s
– The name of the locale, for instancesv_SE
for Swedish oren_US
for US English.
logFooter | top |
The message that is logged to info
level
after the task has been successfully run.
- Setter method:
setLogFooter(String s)
parameters:s
– The footer message.- Default value:
- Empty (no footer message is logged.)
- See also:
- logHeader
logHeader | top |
The message that is logged to info
level
before the task is run.
- Setter method:
setLogHeader(String s)
parameters:s
– The header message.- Default value:
- A task class specific message.
- See also:
- logFooter
overview | top |
An overview comment file.
- Setter method:
setOverview(Object o)
parameters:
packageNames (required) | top |
The names of the Java packages to document. If this is used together with the subPackages property, all subpackages of the packages are included.
- Setter method:
addPackageName(String s)
Add one package name.parameters:s
– The package name.- Setter method:
addPackageNames(Object o)
Add one or several package names.parameters:o
– One or an array or collection of package names (strings).- Setter method:
clearPackageNames()
Clear the list of package names.- See also:
- subPackages
- sourceFileNames
quiet | top |
Tell the Javadoc compiler to be quiet.
- Setter method:
setQuiet(boolean b)
parameters:b
– Should the Javadoc command be quiet?- Default value:
false
(not quiet).- See also:
- verbose
reportLevel | top |
This property is used to change the Report level for all task created by this task factory. The report level is changed for the thread running the task when the it is run, and is restored to its previous level when the it is done.
- Setter method:
setReportLevel(Level l)
Set the report levelparameters:l
– The new report level.
sourceCodeVersion | top |
The version of source code accepted.
- Setter method:
setSourceCodeVersion(String s)
parameters:s
– The source code version, for instance1.5
sourceFileNames | top |
A collection of source file names, used as described in
Java's javadoc
tool documentation.
- Setter method:
addSourceFileName(String s)
Add one source file.parameters:s
– The name of the source file. May contain wildcards.- Setter method:
addSourceFileNames(Object o)
Add one or several source file names.parameters:o
– One or an array or collection of source file names (strings). May contain wildcards.- Setter method:
clearSourceFileNames()
Clear the list of source file names.- See also:
- packageNames
sources (required) | top |
A collection of source directories that contain the Java files to document.
Since this task is not EntityFS-aware, EntityFilter:s cannot be used to hide source files or directories. This task will create Javadoc documentation for all files under the added source directories.
- Setter method:
addSource(Object o)
Add one or several source directories.parameters:- Setter method:
addSources(Object o)
Add one or several source directories.parameters:- Setter method:
clearSources()
Discard all sources.- Setter method:
setSource(Object o)
Set one or several source directories and discard previously set source directories.parameters:- Setter method:
setSources(Object o)
Set one or several source directories and discard previously set source directories.parameters:
stderrStrategy | top |
A ProcessOutputStrategy
for handling the program's output to stderr
.
- Setter method:
setStderrStrategy(ProcessOutputStrategy s)
parameters:s
– Thestderr
strategy.- Default value:
- A LoggingProcessOutputStrategy
that logs output to the
Level.SEVERE
- See also:
- stdoutStrategy
stdoutStrategy | top |
A ProcessOutputStrategy
for handling the program's output to stdout
.
- Setter method:
setStdoutStrategy(ProcessOutputStrategy s)
parameters:s
– Thestdout
strategy.- Default value:
- A LoggingProcessOutputStrategy
that logs output to the
Level.INFO
- See also:
- stderrStrategy
subPackages | top |
If this is set to true
, documentation for all
subpackages of the packages added to the packageNames
property is also built.
- Setter method:
setSubPackages(boolean b)
parameters:b
– Should subpackages be included?- Default value:
false
(documentation for subpackages is not built).- See also:
- packageNames
- excludePackages
tagletPaths | top |
A list of search paths for finding taglet class files.
This corresponds to the standard doclet's -tagletpath
argument. See
the standard doclet documentation for more details.
- Setter method:
addTagletPath(Object o)
Add one or several taglet paths.parameters:- Setter method:
addTagletPaths(Object o)
Add one or several taglet paths.parameters:- Setter method:
clearTagletPaths()
Clear the list of taglet paths.- See also:
- taglets
taglets | top |
A collection of taglet classes for custom taglets. A tag defined in a custom taglet can be declared by adding it to the tags property.
This corresponds to the standard doclet's -taglet
argument. See
the standard doclet documentation for more details.
- Setter method:
addTaglet(String fqn)
Add one custom taglet.parameters:fqn
– The fully qualified class name of the taglet class.- Setter method:
addTaglets(Object o)
Add one or several custom tagletsparameters:o
– One or an array or collection of taglet class names (strings).- Setter method:
clearTaglets()
Clear the list of custom taglets and custom tags.- See also:
- tags
- tagletPaths
tags | top |
Define custom Javadoc tags and define the order tags should be
presented in the generated documentation. This corresponds to the
-tag
argument to the standard doclet.
The tags are defined in the order that the definitions are added to this property.
This corresponds to the standard doclet's -tag
argument. See
the standard doclet documentation for more details.
Note: Currently (as of JDK 1.6.0_13), Java bug #6447784 makes it impossible to have space characters in the tag text.
- Setter method:
addTag(String s)
Add one custom tagparameters:s
– The string representation of the tag. See the standard doclet documentation.- Setter method:
addTag(JavadocTagDefinition t)
Add one custom tag.parameters:t
– A tag description object.- Setter method:
addTags(Object o)
Add one or several custom tags.parameters:- Setter method:
clearTags()
Clear the list of custom taglets and custom tags.- See also:
- taglets
traceLogging | top |
If trace logging is enabled for a task, it reports its configuration before it is run.
Trace logging may also be enabled globally for all tasks by calling TraceMode.setTraceMode(boolean).
- Setter method:
setTraceLogging(boolean b)
Enable or disable trace logging.parameters:b
– Enable trace logging?
verbose | top |
Tell the Javadoc compiler to be verbose?
- Setter method:
setVerbose(boolean b)
parameters:b
– Should the Javadoc command be verbose?- Default value:
false
(not verbose).- See also:
- quiet
visibilityLevel | top |
Set the lowest visibility level of classes, methods and fields included in the documentation.
- Setter method:
setVisibilityLevel(JavadocVisibilityLevel l)
parameters:l
– The visibility level. This is one of:JavadocVisibilityLevel.PRIVATE
JavadocVisibilityLevel.PACKAGE
JavadocVisibilityLevel.PROTECTED
JavadocVisibilityLevel.PUBLIC
- Default value:
- Unset (
public
andprotected
members will be included).
workingDirectory | top |
The working directory for the program. (The directory that the program is started in.)
- Setter method:
setWorkingDirectory(Object o)
parameters:- Default value:
- The Schmant process' working directory. The Schmant launcher scripts sets this to the directory where the current script file is.
Examples
Example 1
Create API documentation for the Schmant Java source files
in the directory hierarchy under src
. Put the documentation in the
directory doc
. Use the standard doclet (creating HTML
documentation).
JavaScript
Example 2
Create API documentation for the Schmant Java source files
in the directory hierarchy under src
. Put the documentation in the
directory doc
. Use the PDF doclet (creating PDF
documentation).
Groovy
JavaScript
Example 3
Create API documentation for the Schmant Java source files
in the directory hierarchy under src
. Put the documentation in the
directory doc
. Define the custom tag @injar
and
allow it occur in type documentation. Use the standard doclet (creating HTML
documentation).
JavaScript
* That a task is not EntityFS-aware means that it is not aware of DirectoryView filters (it uses them as plain Directory:s) and also that it usually requires that the entities it takes as arguments are in a File-based file file system. (That they are ECFileResolvable.) A non File-resolvable entity can be made so by using the SchmantFileSystems.makeFileResolvable(org.entityfs.EFile) method.