org.apache.tools.ant.taskdefs

Class Gjdoc


public class Gjdoc
extends Task

Generates Javadoc documentation for a collection of source code. It used the Gjdoc tool from GNU classpath.

Current known limitations are:

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

static class
Gjdoc.AccessType
EnumeratedAttribute implementation supporting the javadoc scoping values.
class
Gjdoc.DocletInfo
This class stores info about doclets.
class
Gjdoc.DocletParam
Inner class used to manage doclet parameters.
static class
Gjdoc.ExtensionInfo
A project aware class used for Javadoc extensions which take a name and a path such as doclet and taglet arguments.
class
Gjdoc.GroupArgument
static class
Gjdoc.Html
An HTML element in the javadoc.
class
Gjdoc.LinkArgument
Represents a link triplet (href, whether link is offline, location of the package list if off line)
static class
Gjdoc.PackageName
Used to track info about the packages to be javadoc'd
static class
Gjdoc.SourceFile
This class is used to manage the source files to be processed.
class
Gjdoc.TagArgument
Class representing a -tag argument.

Field Summary

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Method Summary

void
addBottom(Gjdoc.Html text)
Set the text to be placed at the bottom of each output file.
void
addDoctitle(Gjdoc.Html text)
Add a document title to use for the overview page.
void
addExcludePackage(Gjdoc.PackageName pn)
Add a package to be excluded from the javadoc run.
void
addFileset(FileSet fs)
Adds a fileset.
void
addFooter(Gjdoc.Html text)
Set the footer text to be placed at the bottom of each output file.
void
addHeader(Gjdoc.Html text)
Set the header text to be placed at the top of each output file.
void
addPackage(Gjdoc.PackageName pn)
Add a single package to be processed.
void
addPackageset(DirSet packageSet)
Adds a packageset.
void
addSource(Gjdoc.SourceFile sf)
Add a single source file.
void
addTaglet(Gjdoc.ExtensionInfo tagletInfo)
Add a taglet
Commandline.Argument
createArg()
Adds a command-line argument.
Path
createBootclasspath()
Create a Path to be configured with the boot classpath
Path
createClasspath()
Create a Path to be configured with the classpath to use
Gjdoc.DocletInfo
createDoclet()
Create a doclet to be used in the documentation generation.
Gjdoc.GroupArgument
createGroup()
Separates packages on the overview page into whatever groups you specify, one group per table.
Gjdoc.LinkArgument
createLink()
Create link to javadoc output at the given URL.
Path
createSourcepath()
Create a path to be configured with the locations of the source files.
Gjdoc.TagArgument
createTag()
Creates and adds a -tag argument.
void
execute()
Called by the project to let the task do its work.
protected String
expand(String content)
Convenience method to expand properties.
void
setAccess(Gjdoc.AccessType at)
Set the scope to be processed.
void
setAdditionalparam(String add)
Set an additional parameter on the command line
void
setAuthor(boolean b)
Include the author tag in the generated documentation.
void
setBootClasspathRef(Reference r)
Adds a reference to a CLASSPATH defined elsewhere.
void
setBootclasspath(Path path)
Set the boot classpath to use.
void
setBottom(String bottom)
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
setClasspathRef(Reference r)
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
setDoclet(String docletName)
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
setDocletPathRef(Reference r)
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
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 binary javadoc found in Ant's JDK.
void
setExtdirs(String path)
Deprecated. Use the setExtdirs(Path) version.
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)?

Default is false.

void
setFooter(String footer)
Set the footer text to be placed at the bottom of each output file.
void
setGroup(String src)
Group specified packages together in overview page.
void
setHeader(String header)
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
setLink(String src)
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
setLocale(String locale)
Set the local to use in documentation generation.
void
setMaxmemory(String max)
Set the maximum memory to be used by the javadoc process
void
setNodeprecated(boolean b)
Control deprecation infromation
void
setNodeprecatedlist(boolean b)
Control deprecated list generation
void
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 processed
void
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
setPrivate(boolean b)
Indicate whether all classes and members are to be included in the scope processed
void
setProtected(boolean b)
Indicate whether only protected and public classes and members are to be included in the scope processed
void
setPublic(boolean b)
Indicate whether only public classes and members are to be included in the scope processed
void
setSerialwarn(boolean b)
Control warnings about serial tag.
void
setSource(String source)
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 file
void
setSourcepathRef(Reference r)
Adds a reference to a CLASSPATH defined elsewhere.
void
setSplitindex(boolean b)
Generate a split index
void
setStylesheetfile(File f)
Specifies the CSS stylesheet file to use.
void
setUse(boolean b)
Generate the "use&quot 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 mode
void
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

execute, getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, log, log, setProject

Method Details

addBottom

public void addBottom(Gjdoc.Html text)
Set the text to be placed at the bottom of each output file.

Parameters:
text - the bottom text.


addDoctitle

public void addDoctitle(Gjdoc.Html text)
Add a document title to use for the overview page.

Parameters:
text - the HTML element containing the document title.


addExcludePackage

public void addExcludePackage(Gjdoc.PackageName pn)
Add a package to be excluded from the javadoc run.

Parameters:
pn - the name of the package (wildcards are not permitted).


addFileset

public void addFileset(FileSet fs)
Adds a fileset.

All included files will be added as sourcefiles. The task will automatically add includes="**/*.java" to the fileset.

Since:
1.5


addFooter

public void addFooter(Gjdoc.Html text)
Set the footer text to be placed at the bottom of each output file.

Parameters:
text - the footer text.


addHeader

public void addHeader(Gjdoc.Html text)
Set the header text to be placed at the top of each output file.

Parameters:
text - the header text


addPackage

public void addPackage(Gjdoc.PackageName pn)
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.


addPackageset

public void addPackageset(DirSet packageSet)
Adds a packageset.

All included directories will be translated into package names be converting the directory separator into dots.

Since:
1.5


addSource

public void addSource(Gjdoc.SourceFile sf)
Add a single source file.

Parameters:
sf - the source file to be processed.


addTaglet

public void addTaglet(Gjdoc.ExtensionInfo tagletInfo)
Add a taglet

Parameters:
tagletInfo - information about the taglet.


createArg

public Commandline.Argument createArg()
Adds a command-line argument.

Since:
Ant 1.6


createBootclasspath

public Path createBootclasspath()
Create a Path to be configured with the boot classpath

Returns:
a new Path instance to be configured with the boot classpath.


createClasspath

public Path createClasspath()
Create a Path to be configured with the classpath to use

Returns:
a new Path instance to be configured with the classpath.


createDoclet

public Gjdoc.DocletInfo createDoclet()
Create a doclet to be used in the documentation generation.

Returns:
a new DocletInfo instance to be configured.


createGroup

public Gjdoc.GroupArgument createGroup()
Separates packages on the overview page into whatever groups you specify, one group per table.


createLink

public Gjdoc.LinkArgument createLink()
Create link to javadoc output at the given URL.

Returns:
link argument to configure


createSourcepath

public Path 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.


createTag

public Gjdoc.TagArgument 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.


execute

public void execute()
            throws BuildException
Called by the project to let the task do its work. This method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running "ant target1 target2" will run all tasks in target3 twice.
Overrides:
execute in interface Task

Throws:
BuildException - if something goes wrong with the build


expand

protected String expand(String content)
Convenience method to expand properties.


setAccess

public void setAccess(Gjdoc.AccessType at)
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.


setAdditionalparam

public void setAdditionalparam(String add)
Set an additional parameter on the command line

Parameters:
add - the additional command line parameter for the javadoc task.


setAuthor

public void setAuthor(boolean b)
Include the author tag in the generated documentation.

Parameters:
b - true if the author tag should be included.


setBootClasspathRef

public void setBootClasspathRef(Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

Parameters:
r - the reference to an instance defining the bootclasspath.


setBootclasspath

public void setBootclasspath(Path path)
Set the boot classpath to use.

Parameters:
path - the boot classpath.


setBottom

public void setBottom(String bottom)
Set the text to be placed at the bottom of each output file.

Parameters:
bottom - the bottom text.


setBreakiterator

public void setBreakiterator(boolean b)
Enables the -linksource switch, will be ignored if javadoc is not the 1.4 version. Default is false

Since:
Ant 1.6


setCharset

public void setCharset(String src)
Charset for cross-platform viewing of generated documentation.


setClasspath

public void setClasspath(Path path)
Set the classpath to be used for this javadoc run.

Parameters:
path - an Ant Path object containing the compilation classpath.


setClasspathRef

public void setClasspathRef(Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

Parameters:
r - the reference to an instance defining the classpath.


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.


setDestdir

public void setDestdir(File dir)
Set the directory where the Javadoc output will be generated.

Parameters:
dir - the destination directory.


setDocencoding

public void setDocencoding(String enc)
Output file encoding name.

Parameters:
enc - name of the encoding to use.


setDoclet

public void setDoclet(String docletName)
Set the class that starts the doclet used in generating the documentation.

Parameters:
docletName - the name of the doclet class.


setDocletPath

public void setDocletPath(Path docletPath)
Set the classpath used to find the doclet class.

Parameters:
docletPath - the doclet classpath.


setDocletPathRef

public void setDocletPathRef(Reference r)
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.


setDoctitle

public void setDoctitle(String doctitle)
Set the title of the generated overview page.

Parameters:
doctitle - the Document title.


setEncoding

public void setEncoding(String enc)
Set the encoding name of the source files,

Parameters:
enc - the name of the encoding for the source files.


setExcludePackageNames

public void setExcludePackageNames(String packages)
Set the list of packages to be excluded.

Parameters:
packages - a comma separated list of packages to be excluded. This may not include wildcards.


setExecutable

public void setExecutable(String executable)
Sets the actual executable command to invoke, instead of the binary javadoc found in Ant's JDK.

Since:
Ant 1.6.3


setExtdirs

public void setExtdirs(String path)

Deprecated. Use the setExtdirs(Path) version.

Set the location of the extensions directories.

Parameters:
path - the string version of the path.


setExtdirs

public void setExtdirs(Path path)
Set the location of the extensions directories.

Parameters:
path - a path containing the extension directories.


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.


setFooter

public void setFooter(String footer)
Set the footer text to be placed at the bottom of each output file.

Parameters:
footer - the footer text.


setGroup

public void setGroup(String src)
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.


setHeader

public void setHeader(String header)
Set the header text to be placed at the top of each output file.

Parameters:
header - the header text


setHelpfile

public void setHelpfile(File f)
Specifies the HTML help file to use.

Parameters:
f - the file containing help content.


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.

Since:
Ant 1.6.3


setLink

public void setLink(String src)
Create links to javadoc output at the given URL.


setLinkoffline

public void setLinkoffline(String src)
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)


setLinksource

public void setLinksource(boolean b)
Enables the -linksource switch, will be ignored if javadoc is not the 1.4 version. Default is false

Since:
Ant 1.6


setLocale

public void setLocale(String locale)
Set the local to use in documentation generation.

Parameters:
locale - the locale to use.


setMaxmemory

public void setMaxmemory(String max)
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)


setNodeprecated

public void setNodeprecated(boolean b)
Control deprecation infromation

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.


setNohelp

public void setNohelp(boolean b)
Control generation of help link.

Parameters:
b - if true, do not generate help link


setNoindex

public void setNoindex(boolean b)
Control generation of index.

Parameters:
b - if true, do not generate index.


setNonavbar

public void setNonavbar(boolean b)
Control generation of the navigation bar.

Parameters:
b - if true, do not generate navigation bar.


setNoqualifier

public void setNoqualifier(String noqualifier)
Enables the -noqualifier switch, will be ignored if javadoc is not the 1.4 version.

Since:
Ant 1.6


setNotree

public void setNotree(boolean b)
Control class tree generation.

Parameters:
b - if true, do not generate class hierarchy.


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.


setOverview

public void setOverview(File f)
Specify the file containing the overview to be included in the generated documentation.

Parameters:
f - the file containing the overview.


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.


setPackageList

public void setPackageList(String src)
The name of a file containing the packages to process.

Parameters:
src - the file containing the package list.


setPackagenames

public void setPackagenames(String packages)
Set the package names to be processed.

Parameters:
packages - a comma separated list of packages specs (may be wildcarded).

See Also:
for wildcard information.


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.


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.


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.


setSerialwarn

public void setSerialwarn(boolean b)
Control warnings about serial tag.

Parameters:
b - if true, generate warning about the serial tag.


setSource

public void setSource(String source)
Enables the -source switch, will be ignored if javadoc is not the 1.4 version.

Since:
Ant 1.5


setSourcefiles

public void setSourcefiles(String src)
Set the list of source files to process.

Parameters:
src - a comma separated list of source files.


setSourcepath

public void setSourcepath(Path src)
Specify where to find source file

Parameters:
src - a Path instance containing the various source directories.


setSourcepathRef

public void setSourcepathRef(Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

Parameters:
r - the reference containing the source path definition.


setSplitindex

public void setSplitindex(boolean b)
Generate a split index

Parameters:
b - true if the index should be split into a file per letter.


setStylesheetfile

public void setStylesheetfile(File f)
Specifies the CSS stylesheet file to use.

Parameters:
f - the file with the CSS to use.


setUse

public void setUse(boolean b)
Generate the "use&quot page for each package.

Parameters:
b - true if the use page should be generated.


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.


setVerbose

public void setVerbose(boolean b)
Run javadoc in verbose mode

Parameters:
b - true if operation is to be verbose.


setVersion

public void setVersion(boolean b)
Include the version tag in the generated documentation.

Parameters:
b - true if the version tag should be included.


setWindowtitle

public void setWindowtitle(String title)
Set the title to be placed in the HTML <title> tag of the generated documentation.

Parameters:
title - the window title to use.


Copyright B) 2000-2005 Apache Software Foundation. All Rights Reserved.