Javadoc (Apache Ant API)

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


public class Javadoc
extends Task

Generates Javadoc documentation for a collection of source code.

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
Author:
Jon S. Stevens jon@clearink.com
, Stefano Mazzocchi stefano@apache.org , Patrick Chanezon chanezon@netscape.com , Ernst de Haan ernst@jollem.com , Stefan Bodewig

Nested Class Summary
static class Javadoc.AccessType
          EnumeratedAttribute implementation supporting the javadoc scoping values.
 class Javadoc.DocletInfo
          This class stores info about doclets.
 class Javadoc.DocletParam
          Inner class used to manage doclet parameters.
static class Javadoc.ExtensionInfo
          A project aware class used for Javadoc extensions which take a name and a path such as doclet and taglet arguments.
 class Javadoc.GroupArgument
           
static class Javadoc.Html
          An HTML element in the javadoc.
 class Javadoc.LinkArgument
           
static class Javadoc.PackageName
          Used to track info about the packages to be javadoc'd
static class Javadoc.SourceFile
          This class is used to manage the source files to be processed.
 class Javadoc.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
 
Constructor Summary
Javadoc()
           
 
Method Summary
 void 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 addExcludePackage(Javadoc.PackageName pn)
          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 addPackage(Javadoc.PackageName pn)
          Add a single package to be processed.
 void addPackageset(DirSet packageSet)
          Adds a packageset.
 void addSource(Javadoc.SourceFile sf)
          Add a single source file.
 void addTaglet(Javadoc.ExtensionInfo tagletInfo)
          Add a taglet
 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
 Javadoc.DocletInfo createDoclet()
          Create a doclet to be used in the documentation generation.
 Javadoc.GroupArgument createGroup()
          Separates packages on the overview page into whatever groups you specify, one group per table.
 Javadoc.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.
 Javadoc.TagArgument createTag()
          Creates and adds a -tag argument.
 void execute()
          Called by the project to let the task do its work.
protected  java.lang.String expand(java.lang.String content)
          Convenience method to expand properties.
 void setAccess(Javadoc.AccessType at)
          Set the scope to be processed.
 void setAdditionalparam(java.lang.String add)
          Set an additional parameter on the command line
 void setAuthor(boolean b)
          Include the author tag in the generated documentation.
 void setBootclasspath(Path path)
          Set the boot classpath to use.
 void setBootClasspathRef(Reference r)
          Adds a reference to a CLASSPATH defined elsewhere.
 void setBottom(java.lang.String bottom)
          Set the text to be placed at the bottom of each output file.
 void setCharset(java.lang.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(java.io.File dir)
          Set the directory where the Javadoc output will be generated.
 void setDocencoding(java.lang.String enc)
          Output file encoding name.
 void setDoclet(java.lang.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(java.lang.String doctitle)
          Set the title of the generated overview page.
 void setEncoding(java.lang.String enc)
          Set the encoding name of the source files,
 void setExcludePackageNames(java.lang.String packages)
          Set the list of packages to be excluded.
 void setExtdirs(Path path)
          Set the location of the extensions directories.
 void setExtdirs(java.lang.String path)
          Deprecated. Use the setExtdirs(Path) version.
 void setFailonerror(boolean b)
          Should the build process fail if javadoc fails (as indicated by a non zero return code)?
 void setFooter(java.lang.String footer)
          Set the footer text to be placed at the bottom of each output file.
 void setGroup(java.lang.String src)
          Group specified packages together in overview page.
 void setHeader(java.lang.String header)
          Set the header text to be placed at the top of each output file.
 void setHelpfile(java.io.File f)
          Specifies the HTML help file to use.
 void setLink(java.lang.String src)
          Create links to javadoc output at the given URL.
 void setLinkoffline(java.lang.String src)
          Link to docs at "url" using package list at "url2" - separate the URLs by using a space character.
 void setLocale(java.lang.String locale)
          Set the local to use in documentation generation.
 void setMaxmemory(java.lang.String max)
          Set the maximum memory to be used by the javadoc process
 void setNodeprecated(boolean b)
          If true, do not include @deprecated information.
 void setNodeprecatedlist(boolean b)
          If true, do not generate deprecated list.
 void setNohelp(boolean b)
          If true, do not generate help link
 void setNoindex(boolean b)
          If true, do not generate index.
 void setNonavbar(boolean b)
          If true, do not generate navigation bar.
 void setNotree(boolean b)
          If true, do not generate class hierarchy.
 void setOld(boolean b)
          Indicate whether Javadoc should produce old style (JDK 1.1) documentation.
 void setOverview(java.io.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(java.lang.String src)
          The name of a file containing the packages to process.
 void setPackagenames(java.lang.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)
          If true, generate warning about @serial tag.
 void setSource(java.lang.String source)
          Enables the -source switch, will be ignored if javadoc is not the 1.4 version or a different doclet than the standard doclet is used.
 void setSourcefiles(java.lang.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(java.io.File f)
          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 mode
 void setVersion(boolean b)
          Include the version tag in the generated documentation.
 void setWindowtitle(java.lang.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
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorOutput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Javadoc


public Javadoc()
Method Detail

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


public void setMaxmemory(java.lang.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)

setAdditionalparam


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

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

setSourcepath


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

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

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.

setSourcepathRef


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

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

setDestdir


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

Parameters:
dir - the destination directory.

setSourcefiles


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

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

addSource


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

Parameters:
sf - the source file to be processed.

setPackagenames


public void setPackagenames(java.lang.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.

addPackage


public void addPackage(Javadoc.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.

setExcludePackageNames


public void setExcludePackageNames(java.lang.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.

addExcludePackage


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

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

setOverview


public void setOverview(java.io.File f)
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


public void setAccess(Javadoc.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.

setDoclet


public void setDoclet(java.lang.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.

createDoclet


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

Returns:
a new DocletInfo instance to be configured.

addTaglet


public void addTaglet(Javadoc.ExtensionInfo tagletInfo)
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


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.

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.

setClasspathRef


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

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

setBootclasspath


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

Parameters:
path - the boot classpath.

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.

setBootClasspathRef


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

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

setExtdirs


public void setExtdirs(java.lang.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.

setVerbose


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

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

setLocale


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

Parameters:
locale - the locale to use.

setEncoding


public void setEncoding(java.lang.String enc)
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


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

Parameters:
title - the window title to use.

setDoctitle


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

Parameters:
doctitle - the Document title.

addDoctitle


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

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

setHeader


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

Parameters:
header - the header text

addHeader


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

Parameters:
text - the header text

setFooter


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

Parameters:
footer - the footer text.

addFooter


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

Parameters:
text - the footer text.

setBottom


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

Parameters:
bottom - the bottom text.

addBottom


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

Parameters:
text - the bottom text.

setLinkoffline


public void setLinkoffline(java.lang.String src)
Link to docs at "url" using package list at "url2" - separate the URLs by using a space character.


setGroup


public void setGroup(java.lang.String src)
Group specified packages together in overview page.


setLink


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


setNodeprecated


public void setNodeprecated(boolean b)
If true, do not include @deprecated information.


setNodeprecatedlist


public void setNodeprecatedlist(boolean b)
If true, do not generate deprecated list.


setNotree


public void setNotree(boolean b)
If true, do not generate class hierarchy.


setNoindex


public void setNoindex(boolean b)
If true, do not generate index.


setNohelp


public void setNohelp(boolean b)
If true, do not generate help link


setNonavbar


public void setNonavbar(boolean b)
If true, do not generate navigation bar.


setSerialwarn


public void setSerialwarn(boolean b)
If true, generate warning about @serial tag.


setStylesheetfile


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


setHelpfile


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


setDocencoding


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


setPackageList


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


createLink


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


createTag


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


createGroup


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


setCharset


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


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.


setSource


public void setSource(java.lang.String source)
Enables the -source switch, will be ignored if javadoc is not the 1.4 version or a different doclet than the standard doclet is used.

Since:
Ant 1.5

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

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

execute


public void execute()
             throws BuildException
Description copied from class: Task
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 class Task
Throws:
BuildException - if something goes wrong with the build

expand


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



Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.