Built by Maven

tycho-document-bundle:javadoc

Full name:

org.eclipse.tycho.extras:tycho-document-bundle-plugin:5.0.0-SNAPSHOT:javadoc

Description:

Create the javadoc based API reference for this bundle.
This mojo creates the javadoc documentation by calling the javadoc application from the command line. In addition it creates a ready to include toc-xml file for the Eclipse Help system.
The sources for creating the javadoc are generated automatically based on the dependency that this project has. As dependency you can specify any other maven project, for example the feature project that references you other bundles. Included features will be added to the list.

The javadoc executable path is determined in this order:

  • executable argument of the javadocOptions configuration element, if available
  • active Maven toolchain
  • java.home system property
  • JAVA_HOME environment setting
  • if none of the above can be used, the javadoc executable is invoked without an explicit path and relies on the operating system PATH variable

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile+runtime.
  • The goal is not marked as thread-safe and thus does not support parallel builds.
  • Since version: 0.20.0.
  • Binds by default to the lifecycle phase: process-classes.

Required Parameters

Name Type Since Description
<buildDirectory> File - The build directory where temporary build files will be placed
User Property: project.build.directory
<outputDirectory> File - The directory where the javadoc content will be generated
Default: ${project.build.directory}/reference/api
User Property: outputDirectory

Optional Parameters

Name Type Since Description
<cleanFirst> boolean - An option to clean out the whole outputDirectory first.
Default: true
User Property: cleanFirst
<javadocOptions> JavadocOptions - Options for calling the javadoc application. Possible options are (all options are optional):
  • ignoreError, specifies if errors calling javadoc should be ignored
  • doclet, used as javadoc -doclet parameter
  • docletArtifacts, dependencies will be resovled and added as -docletpath parameter
  • encoding, used as javadoc -encoding parameter (default: ${project.build.sourceEncoding}
  • additionalArguments, a list of additional arguments passed to javadoc
  • includes/excludes, the list of names of packages to be included in or excluded from JavaDoc processing; use '*' character as wildcard
  • executable, the javadoc executable path to be used (see mojo description for the default path calculation)
Example configuration: 
<configuration>
   <javadocOptions>
      <ignoreError>false</ignoreError>
      <encoding>UTF-8</encoding>
      <doclet>foo.bar.MyDoclet</doclet>
      <docletArtifacts>
         <docletArtifact>
            <groupId>foo.bar</groupId>
            <artifactId>foo.bar.mydocletartifact</artifactId>
            <version>1.0</version>
         </docletArtifact>
      </docletArtifacts>
      <includes>
         <include>com.example.*</include>
      </includes>
      <excludes>
         <exclude>com.example.internal.*</exclude>
      </excludes>
      <additionalArguments>
         <additionalArgument>-windowtitle "The Window Title"</additionalArgument>
         <additionalArgument>-nosince</additionalArgument>
      </additionalArguments>
   </javadocOptions>
</configuration>

User Property: javadocOptions
<scopes> Set<String> - The scopes that the dependencies must have in order to be included
Default: compile,provided
User Property: scopes
<skipTocGen> boolean - Set this property to true to skip the generation of the Eclipse TOC files.
Default: false
User Property: skipTocGen
<sourceTypes> Set<String> - Maven module types that will be used to include the source
Default: eclipse-plugin
User Property: sourceTypes
<tocFile> File - The output location of the toc file.
This file will be overwritten.
Default: ${project.build.directory}/tocjavadoc.xml
User Property: tocFile
<tocOptions> TocOptions - Options for creating the toc files.
  • mainLabel, specifies the main label of the toc file (default: "API Reference")
  • mainFilename, specifies the filename of the TOC file (default: "overview-summary.html")
Example configuration: 
<configuration>
   <tocOptions>
      <mainLabel>My own label</mainLabel>
      <mainFilename>myOverviewSummary.html</mainFilename>
   </tocOptions>
</configuration>

User Property: tocOptions

Parameter Details

<buildDirectory>

The build directory where temporary build files will be placed
  • Type: java.io.File
  • Required: Yes
  • User Property: project.build.directory

<cleanFirst>

An option to clean out the whole outputDirectory first.
  • Type: boolean
  • Required: No
  • User Property: cleanFirst
  • Default: true

<javadocOptions>

Options for calling the javadoc application. Possible options are (all options are optional):
  • ignoreError, specifies if errors calling javadoc should be ignored
  • doclet, used as javadoc -doclet parameter
  • docletArtifacts, dependencies will be resovled and added as -docletpath parameter
  • encoding, used as javadoc -encoding parameter (default: ${project.build.sourceEncoding}
  • additionalArguments, a list of additional arguments passed to javadoc
  • includes/excludes, the list of names of packages to be included in or excluded from JavaDoc processing; use '*' character as wildcard
  • executable, the javadoc executable path to be used (see mojo description for the default path calculation)
Example configuration: 
<configuration>
   <javadocOptions>
      <ignoreError>false</ignoreError>
      <encoding>UTF-8</encoding>
      <doclet>foo.bar.MyDoclet</doclet>
      <docletArtifacts>
         <docletArtifact>
            <groupId>foo.bar</groupId>
            <artifactId>foo.bar.mydocletartifact</artifactId>
            <version>1.0</version>
         </docletArtifact>
      </docletArtifacts>
      <includes>
         <include>com.example.*</include>
      </includes>
      <excludes>
         <exclude>com.example.internal.*</exclude>
      </excludes>
      <additionalArguments>
         <additionalArgument>-windowtitle "The Window Title"</additionalArgument>
         <additionalArgument>-nosince</additionalArgument>
      </additionalArguments>
   </javadocOptions>
</configuration>
  • Type: org.eclipse.tycho.extras.docbundle.JavadocOptions
  • Required: No
  • User Property: javadocOptions

<outputDirectory>

The directory where the javadoc content will be generated
  • Type: java.io.File
  • Required: Yes
  • User Property: outputDirectory
  • Default: ${project.build.directory}/reference/api

<scopes>

The scopes that the dependencies must have in order to be included
  • Type: java.util.Set<java.lang.String>
  • Required: No
  • User Property: scopes
  • Default: compile,provided

<skipTocGen>

Set this property to true to skip the generation of the Eclipse TOC files.
  • Type: boolean
  • Required: No
  • User Property: skipTocGen
  • Default: false

<sourceTypes>

Maven module types that will be used to include the source
  • Type: java.util.Set<java.lang.String>
  • Required: No
  • User Property: sourceTypes
  • Default: eclipse-plugin

<tocFile>

The output location of the toc file.
This file will be overwritten.
  • Type: java.io.File
  • Required: No
  • User Property: tocFile
  • Default: ${project.build.directory}/tocjavadoc.xml

<tocOptions>

Options for creating the toc files.
  • mainLabel, specifies the main label of the toc file (default: "API Reference")
  • mainFilename, specifies the filename of the TOC file (default: "overview-summary.html")
Example configuration: 
<configuration>
   <tocOptions>
      <mainLabel>My own label</mainLabel>
      <mainFilename>myOverviewSummary.html</mainFilename>
   </tocOptions>
</configuration>
  • Type: org.eclipse.tycho.extras.docbundle.TocOptions
  • Required: No
  • User Property: tocOptions