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:
java.lang.Cloneable
public class Javadoc
extends Task
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

  • Constructor Details

  • 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

      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.

    • createArg

      public Commandline.Argument createArg()
      Adds a command-line argument.
      Returns:
      a command-line argument to configure
      Since:
      Ant 1.6

    • 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.

    • setModulePath

      public void setModulePath​(Path mp)
      Specify where to find modules
      Parameters:
      mp - a Path instance containing the modules.
      Since:
      Ant 1.10.6

    • createModulePath

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

      public void setModulePathref​(Reference r)
      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

      public void setModuleSourcePath​(Path mp)
      Specify where to find sources for modules
      Parameters:
      mp - a Path instance containing the sources for modules.
      Since:
      Ant 1.10.6

    • createModuleSourcePath

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

      public void setModuleSourcePathref​(Reference r)
      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

      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.

    • setModulenames

      public void setModulenames​(java.lang.String modules)
      Set the module names to be processed.
      Parameters:
      modules - a comma separated list of module names
      Since:
      Ant 1.10.6

    • 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.

    • addModule

      public void addModule​(Javadoc.PackageName mn)
      Add a single module to be processed.
      Parameters:
      mn - the module name
      Since:
      Ant 1.10.6

    • 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

      @Deprecated public void setExtdirs​(java.lang.String path)
      Deprecated.
      since 1.5.x. 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.
      Parameters:
      src - the offline link specification (url and package list)

    • setGroup

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

    • setLink

      public void setLink​(java.lang.String src)
      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

    • setNonavbar

      public void setNonavbar​(boolean b)
      Control generation of the navigation bar.
      Parameters:
      b - if true, do not generate navigation bar.

    • setSerialwarn

      public void setSerialwarn​(boolean b)
      Control warnings about serial tag.
      Parameters:
      b - if true, generate warning about the serial tag.

    • setStylesheetfile

      public void setStylesheetfile​(java.io.File f)
      Specifies the CSS stylesheet file to use.
      Parameters:
      f - the file with the CSS to use.

    • setHelpfile

      public void setHelpfile​(java.io.File f)
      Specifies the HTML help file to use.
      Parameters:
      f - the file containing help content.

    • setDocencoding

      public void setDocencoding​(java.lang.String enc)
      Output file encoding name.
      Parameters:
      enc - name of the encoding to use.

    • setPackageList

      public void setPackageList​(java.lang.String src)
      The name of a file containing the packages to process.
      Parameters:
      src - the file containing the package list.

    • createLink

      public Javadoc.LinkArgument createLink()
      Create link to Javadoc output at the given URL.
      Returns:
      link argument to configure

    • 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.
      Returns:
      tag argument to be configured

    • createGroup

      public Javadoc.GroupArgument createGroup()
      Separates packages on the overview page into whatever groups you specify, one group per table.
      Returns:
      a group argument to be configured

    • setCharset

      public void setCharset​(java.lang.String src)
      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 - a boolean 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 - a boolean value
      Since:
      Ant 1.9.4

    • setSource

      public void setSource​(java.lang.String source)
      Enables the -source switch, will be ignored if Javadoc is not the 1.4 version.
      Parameters:
      source - a String value
      Since:
      Ant 1.5

    • setExecutable

      public void setExecutable​(java.lang.String executable)
      Sets the actual executable command to invoke, instead of the binary javadoc found in Ant's JDK.
      Parameters:
      executable - the command to invoke.
      Since:
      Ant 1.6.3

    • 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.

      Parameters:
      packageSet - a directory set
      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.

      Parameters:
      fs - a file set
      Since:
      1.5

    • createSourceFiles

      public Javadoc.ResourceCollectionContainer 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 - a String 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 - a String value
      Since:
      Ant 1.6

    • setNoqualifier

      public void setNoqualifier​(java.lang.String noqualifier)
      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 - a boolean value.
      Since:
      Ant 1.6.3

    • setDocFilesSubDirs

      public void setDocFilesSubDirs​(boolean b)
      Enables deep-copying of doc-files directories.
      Parameters:
      b - boolean
      Since:
      Ant 1.8.0

    • setExcludeDocFilesSubDir

      public void setExcludeDocFilesSubDir​(java.lang.String s)
      Colon-separated list of doc-files subdirectories to skip if docFilesSubDirs 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

      public void execute() throws BuildException
      Execute the task.
      Overrides:
      execute in class Task
      Throws:
      BuildException - on error

    • expand

      protected java.lang.String expand​(java.lang.String content)
      Convenience method to expand properties.
      Parameters:
      content - the string to expand
      Returns:
      the converted string