Tycho Document Bundle Plugin – tycho-document-bundle:javadoc

tycho-document-bundle:javadoc

Full name:

org.eclipse.tycho.extras:tycho-document-bundle-plugin:3.0.0: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`	`0.20.0`	The build directory where temporary build files will be placed User property is: `project.build.directory`.
`<outputDirectory>`	`File`	`0.20.0`	The directory where the javadoc content will be generated Default value is: `${project.build.directory}/reference/api`. User property is: `outputDirectory`.

Optional Parameters

Name	Type	Since	Description
`<cleanFirst>`	`boolean`	`0.20.0`	An option to clean out the whole outputDirectory first. Default value is: `true`. User property is: `cleanFirst`.
`<javadocOptions>`	`JavadocOptions`	`0.20.0`	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 is*: `javadocOptions`.
`<scopes>`	`Set`	`0.20.0`	The scopes that the dependencies must have in order to be included Default value is: `compile,provided`. User property is: `scopes`.
`<skipTocGen>`	`boolean`	`0.20.0`	Set this property to true to skip the generation of the Eclipse TOC files. Default value is: `false`. User property is: `skipTocGen`.
`<sourceTypes>`	`Set`	`0.20.0`	Maven module types that will be used to include the source Default value is: `eclipse-plugin`. User property is: `sourceTypes`.
`<tocFile>`	`File`	`0.20.0`	The output location of the toc file. This file will be overwritten. Default value is: `${project.build.directory}/tocjavadoc.xml`. User property is: `tocFile`.
`<tocOptions>`	`TocOptions`	`0.20.0`	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 is: `tocOptions`.

Parameter Details

<buildDirectory>

The build directory where temporary build files will be placed

Type: java.io.File
Since: 0.20.0
Required: Yes
User Property: project.build.directory

<cleanFirst>

An option to clean out the whole outputDirectory first.

Type: boolean
Since: 0.20.0
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
Since: 0.20.0
Required: No
User Property: javadocOptions

<outputDirectory>

The directory where the javadoc content will be generated

Type: java.io.File
Since: 0.20.0
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
Since: 0.20.0
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
Since: 0.20.0
Required: No
User Property: skipTocGen
Default: false

<sourceTypes>

Maven module types that will be used to include the source

Type: java.util.Set
Since: 0.20.0
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
Since: 0.20.0
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
Since: 0.20.0
Required: No
User Property: tocOptions