Javadoc Plugin (quokka.plugin.javadoc:0.3, namespace=javadoc)
The Javadoc plugin generates a javadoc api report for the project
Main Targets
| report | Generates a Javadoc report for the project source code. Implements quokka.plugin.devreport:generate |
Minor Targets
| collect | Collects source and classpaths. Implements quokka.plugin.devreport:generate |
| propogate | Propogates source and class paths to parent projects for aggregation. Implements quokka.plugin.devreport:generate |
| aggregate-report | Generates an aggregated Javadoc report from sub projects. Implements quokka.plugin.devreport:generate |
The Javadoc plugin can be used to generate Javadocs for a single project, or aggregate javadocs from sub-projects.
Single Project Configuration
For the simple case of a single project, just include the plugin as follows:
<plugin group="quokka.plugin.javadoc" version="?"/>
You can then use the javadoc:report or javadoc (an alias) to generate the Javadocs. Javadocs will also be included automatically in the reports target.
Multiple Project Configuration
For multiple project builds where you want to produce an aggregated Javadocs report containing sources from the sub projects, you need to enable the aggregate-report target in the parent project as follows:
<plugin group="quokka.plugin.javadoc" version="?" use-defaults="false" targets="aggregate-report"/>
In the parent project's build.xml file, you'll need to define the sub-projects to aggregate and then run the aggregate-report target as follows:
<target name="javadocs-all">
<subant target="javadoc:collect" buildpath="modules/module1:modules/modulen"/>
<run-target target="javadoc:aggregate-report"/>
</target>
In the sub-projects, you need to enable the collect target. The collect target is enabled by default via the report target. However, if you don't want to generate Javadocs reports in the sub-projects you can override the defaults and only enable the collect target as follow:
<plugin group="quokka.plugin.javadoc" version="?" use-defaults="false" targets="collect"/>
You can now generate an aggregated Javadoc report for sub-projects using the javadocs-all target you defined.
Shared Properties
The following properties are valid for both the report and aggregate-report targets.
Properties:
| destDir | Destination directory for output files |
| maxMemory | Max amount of memory to allocate to the javadoc VM |
| packageNames | Comma separated list of package files (with terminating
wildcard) -- see also the nested package element. |
| packageList | The name of a file containing the packages to process |
| bootClassPath | Override location of class files loaded by the bootstrap class loader |
| bootClassPathRef | Override location of class files loaded by the bootstrap class loader by reference to a PATH defined elsewhere. |
| extDirs | Override location of installed extensions |
| overview | Read overview documentation from HTML file |
| access | Access mode: one of public, protected,
package, or private. default is protected
|
| public | Show only public classes and members |
| protected | Show protected/public classes and members (default) |
| package | Show package/protected/public classes and members |
| private | Show all classes and members |
| old | Generate output using JDK 1.1 emulating doclet |
| verbose | Output messages about what Javadoc is doing |
| locale | Locale to be used, e.g. en_US or en_US_WIN |
| encoding | Source file encoding name |
| version | Include @version paragraphs |
| use | Create class and package usage pages |
| author | Include @author paragraphs |
| splitIndex | Split index into one file per letter |
| windowTitle | Browser window title for the documentation (text) |
| docTitle | Include title for the package index(first) page (html-code) |
| header | Include header text for each page (html-code) |
| footer | Include footer text for each page (html-code) |
| bottom | Include bottom text for each page (html-code) |
| link | Create links to javadoc output at the given URL
-- see also the nested link element. |
| linkOffline | Link to docs at <url> using package list at
<url2> - separate the URLs by using a space character -- see
also the nested link element. |
| group | Group specified packages together in overview
page. The format is as described below -- see also the nested
group element. |
| noDeprecated | Do not include @deprecated information |
| noDeprecatedList | Do not generate deprecated list |
| noTree | Do not generate class hierarchy |
| noIndex | Do not generate index |
| noHelp | Do not generate help link |
| noNavBar | Do not generate navigation bar |
| serialWarn | Generate warning about @serial tag |
| helpFile | Specifies the HTML help file to use |
| stylesheetFile | Specifies the CSS stylesheet to use |
| charset | Charset for cross-platform viewing of generated documentation |
| docEncoding | Output file encoding name |
| doclet | Specifies the class file that starts the doclet
used in generating the documentation -- see also the nested
doclet element. |
| docletPath | Specifies the path to the doclet class file that is specified with the -doclet option. |
| docletPathRef | Specifies the path to the doclet class file that is specified with the -doclet option by reference to a PATH defined elsewhere. |
| additionalParam | Lets you add additional parameters to the javadoc
command line. Useful for doclets. Parameters containing spaces
need to be quoted using " -- see also the nested
arg element. |
| failOnError | Stop the buildprocess if the command exits with a returncode other than 0. |
| excludePackageNames | comma separated list of packages you don't want
docs for -- see also the nested excludepackage element. |
| defaultExcludes | indicates whether default excludes should be used
(yes | no); default excludes are used when omitted. |
| useExternalFile | indicates whether the sourcefile name specified
in srcfiles or as nested source elements should be written to a
temporary file to make the command line shorter. Also applies to
the package names specified via the packageNames attribute or
nested package elements. Also applies
to all the other command line options.
(yes | no). Default is no. |
| source | Necessary to enable javadoc to handle assertions
present in J2SE v 1.4 source code. Set this to "1.4" to
documents code that compiles using "javac -source
1.4".A default value for this attribute can be provided using the magic ant.build.javac.source
property. |
| linkSource | Generate hyperlinks to source files.
(yes | no). Default is no. |
| breakIterator | Use the new breakiterator algorithm.
(yes | no). Default is no. |
| noQualifier | Enables the -noqualifier argument -
must be all or a colon separated list of packages.
|
| includeNoSourcePackages | If set to true, packages that don't contain Java source but a package.html will get documented as well. |
| executable | Specify a particular javadoc executable
to use in place of the default binary (found in the same JDK as Ant is running in).
|
Shared Default Properties
| q.javadoc.defaults.source | ${@setifdef q.project.java.source} | |
| q.javadoc.defaults.maxMemory | ${@setifdef q.project.forkMaxMemory} |
report
Generates a Javadoc report for the project source code
- alias: javadoc
- depends: collect
- prefix: q.javadoc.report
- Implements: quokka.plugin.devreport:generate
Default Properties
| * | q.javadoc.defaults |
| description | Javadoc APIs |
| destDir | ${q.devreport.reportsRootDir}/javadocs |
| indexFile | ${prefix.destDir}/index.html |
| name | Javadocs |
| report.toDir | ${prefix.destDir} |
collect
Collects source and classpaths
- prefix: q.javadoc.collect
- enabled-by-default: false
- Implements: quokka.plugin.devreport:generate
Default Properties
| aggregate | true |
| propogate | true |
| sourcePath | ${q.project.sourceDir}/main/java |
propogate
Propogates source and class paths to parent projects for aggregation
- prefix: q.javadoc.propogate
- enabled-by-default: false
- Implements: quokka.plugin.devreport:generate
aggregate-report
Generates an aggregated Javadoc report from sub projects
- prefix: q.javadoc.aggregate-report
- enabled-by-default: false
- Implements: quokka.plugin.devreport:generate
Default Properties
| * | q.javadoc.defaults |
| description | Javadoc APIs (aggregate) |
| destDir | ${q.devreport.reportsRootDir}/javadocs-aggregate |
| indexFile | ${prefix.destDir}/index.html |
| name | Javadocs |
| report.toDir | ${prefix.destDir} |
Plugin Paths
runtime : Runtime class path
quokka.plugin.devreport devreport 0.3
quokka.core.plugin-spi plugin-spi 0.3
apache.ant ant 1.7.1