This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new ad3363f6 Refresh the site documentation and README
ad3363f6 is described below
commit ad3363f61281d033a09a88edac6a0ace460a5544
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 18 01:08:04 2026 +0000
Refresh the site documentation and README
---
README.md | 125 +++++++++------------
.../examples/aggregate-dependency-sources.md.vm | 4 +-
src/site/markdown/examples/aggregate.md.vm | 2 +-
src/site/markdown/examples/alternate-doclet.md.vm | 96 +++++++++-------
.../markdown/examples/alternate-javadoc-tool.md.vm | 84 ++++++++++++--
src/site/markdown/examples/javadoc-resources.md.vm | 10 +-
.../markdown/examples/links-configuration.md.vm | 18 +--
src/site/markdown/faq.md | 48 ++++----
src/site/markdown/{index.md => index.md.vm} | 69 +++++++++---
src/site/markdown/usage.md.vm | 2 +-
src/site/site.xml | 2 +-
11 files changed, 286 insertions(+), 174 deletions(-)
diff --git a/README.md b/README.md
index 5d8dc1fa..5fddd139 100644
--- a/README.md
+++ b/README.md
@@ -14,72 +14,59 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-Contributing to [Apache Maven Javadoc
Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/)
-======================
-
-[][license]
-[](https://search.maven.org/artifact/org.apache.maven.plugins/maven-javadoc-plugin)
-[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-javadoc-plugin/README.md)
-[][build]
-[][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss
your changes
- on the [dev list][ml-list] first.
- This way you can make sure you're not wasting your time on something that
isn't
- considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
- + Clearly describe the issue, including steps to reproduce when it is a bug.
- + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is
the
-main channel of communication for contributors.
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually
the master branch).
- Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
- patches should only highlight the actual difference, not being disturbed by
any formatting issues:
- + Only use spaces for indentation.
- + Create minimal diffs - disable on save actions like reformat source code
or organize imports.
- If you feel the source code should be reformatted, create a separate PR
for this change.
- + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon
Account](https://mastodon.social/deck/@[email protected])
-+ `#Maven channel` on [ASFs Slack](https://the-asf.slack.com)
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-javadoc-plugin/job/master/lastCompletedBuild/testReport/
-[build]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-javadoc-plugin/job/master/
+# Apache Maven Javadoc Plugin
+
+[](https://www.apache.org/licenses/LICENSE-2.0)
+[](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin)
+[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-javadoc-plugin/README.md)
+[](https://github.com/apache/maven-javadoc-plugin/actions/workflows/maven.yml)
+
+Generates API documentation for a Maven project with the Javadoc tool of the
+JDK, packages it as the `-javadoc.jar` that Maven Central expects next to a
+release, and adds it to the project site as a report.
+
+```shell
+mvn javadoc:javadoc # one module, into target/reports/apidocs
+mvn javadoc:aggregate # all modules of a multi-module build
+mvn javadoc:jar # the -javadoc.jar
+```
+
+The plugin needs Maven 3.9.0 or later and Java 8 or later.
+
+- Documentation: <https://maven.apache.org/plugins/maven-javadoc-plugin/>
+- Issues: <https://github.com/apache/maven-javadoc-plugin/issues>
+- Security reports: see [SECURITY.md](SECURITY.md); never a public issue
+
+## Build
+
+Build the plugin and install it into your local repository:
+
+```shell
+mvn install
+```
+
+The integration tests under `src/it/projects` run with the `run-its`
+profile. To run all of them, or one by its directory name:
+
+```shell
+mvn -Prun-its verify
+mvn -Prun-its verify -Dinvoker.test=MJAVADOC-137_jar
+```
+
+Before you push, check formatting and license headers:
+
+```shell
+mvn spotless:check apache-rat:check
+```
+
+`mvn spotless:apply` fixes the formatting. Run it with JDK 17 or 21.
+
+## Contributing
+
+Open a pull request against `master` on GitHub. Discuss larger changes on the
+[developer mailing list](https://maven.apache.org/mailing-lists.html) or in an
+issue first. Add a unit test or an integration test for each fix, keep
+formatting changes out of functional pull requests, and see the
+[guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html)
+for more. Contributors who send more than the occasional patch are asked to
+file an [Apache Individual Contributor License
Agreement](https://www.apache.org/licenses/#clas).
diff --git a/src/site/markdown/examples/aggregate-dependency-sources.md.vm
b/src/site/markdown/examples/aggregate-dependency-sources.md.vm
index ba886119..0f8a32ee 100644
--- a/src/site/markdown/examples/aggregate-dependency-sources.md.vm
+++ b/src/site/markdown/examples/aggregate-dependency-sources.md.vm
@@ -60,7 +60,7 @@ Preparing Dependencies for Aggregation
Dependency-driven javadoc aggregation works by resolving the sources for
included dependencies, then including these sources in the javadoc production
process for your project. As is common practice with Maven, dependency sources
will be resolved from other modules in the current reactor if they are
available there. Otherwise, the plugin will attempt to resolve the appropriate
sources artifact for the dependency: `sources` for main javadocs,
`test-sources` for test javadocs. **NOTE: If y [...]
-The recommended method for producing these source artifacts is the
[maven-source-plugin](http://maven.apache.org/plugins/maven-source-plugin/).
The following simple example shows how to produce source artifacts:
+The recommended method for producing these source artifacts is the
[maven-source-plugin](https://maven.apache.org/plugins/maven-source-plugin/).
The following simple example shows how to produce source artifacts:
```xml
<project>
@@ -73,7 +73,7 @@ The recommended method for producing these source artifacts
is the [maven-source
[...]
<plugin>
<artifactId>maven-source-plugin</artifactId>
- <version>2.1.1</version>
+ <version>3.4.0</version>
<executions>
<execution>
<id>bundle-sources</id>
diff --git a/src/site/markdown/examples/aggregate.md.vm
b/src/site/markdown/examples/aggregate.md.vm
index 67454d3a..6fe5fc87 100644
--- a/src/site/markdown/examples/aggregate.md.vm
+++ b/src/site/markdown/examples/aggregate.md.vm
@@ -82,7 +82,7 @@ Since 3.1.0 the `aggregate` has changed a little bit. It'll
generate aggregated
Using The `aggregate` Goals
---------------------------
-The [<aggregate/>](../javadoc-mojo.html#aggregate) parameter doesn't
include generate source directories defined using the
[build-helper:add-source](http://mojo.codehaus.org/build-helper-maven-plugin/add-source-mojo.html).
In this case, you need to use the `aggregate` goal and `test-aggregate` goals.
You could define these goals in the <build/> element (using the
<execution/> tag) or <reporting/> element (using the
<reportSet/> tag) as shown below. For more [...]
+To aggregate the Javadoc of all modules, including source directories added
with
[build-helper:add-source](https://www.mojohaus.org/build-helper-maven-plugin/add-source-mojo.html),
use the `aggregate` and `test-aggregate` goals. You could define these goals
in the <build/> element (using the <execution/> tag) or
<reporting/> element (using the <reportSet/> tag) as shown below.
For more information, refer to the [Selective Javadocs Reports
page](./selective-javadoc [...]
```xml
<project>
diff --git a/src/site/markdown/examples/alternate-doclet.md.vm
b/src/site/markdown/examples/alternate-doclet.md.vm
index 41b0d496..d1216cc4 100644
--- a/src/site/markdown/examples/alternate-doclet.md.vm
+++ b/src/site/markdown/examples/alternate-doclet.md.vm
@@ -29,71 +29,85 @@ under the License.
To generate output from an alternate doclet, add configuration similar to the
following to your POM.
-In this example, the doclet is UmlGraph
([https://www.spinellis.gr/umlgraph/](https://www.spinellis.gr/umlgraph/)).
UmlGraph allows the declarative specification and drawing of UML class and
sequence diagrams.
+In this example, the doclet is
[UMLDoclet](https://github.com/talsma-ict/umldoclet). It runs the Standard
Doclet
+and adds UML class and package diagrams, as SVG images, to the generated pages.
-**Note about UmlGraph**: You must have the Graphviz binary in your PATH, or
the images will not be generated. For more information about Graphviz, please
refer to [http://www.graphviz.org/](http://www.graphviz.org/).
+```xml
+<project>
+ ...
+ <reporting> (or <build>)
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
+ <docletArtifact>
+ <groupId>nl.talsmasoftware</groupId>
+ <artifactId>umldoclet</artifactId>
+ <version>2.2.1</version>
+ </docletArtifact>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting> (or </build>)
+ ...
+</project>
+```
-<!--
MACRO{snippet|id=umlgraph|file=target/it/examples/alternate-doclet/pom.xml} -->
+After executing `mvn site`, the class pages in `target/site/apidocs` show the
diagrams, and each class and package
+has an `.svg` file next to its HTML page.
**Note**:
-- [<additionalOptions/>](../javadoc-mojo.html#additionalOptions)
parameter could be used to set additional parameters on the command line,
specifically for doclet options.
--
[<useStandardDocletOptions/>](../javadoc-mojo.html#useStandardDocletOptions)
parameter could be used to specify that the given doclet should use the
[options provided by the Standard
Doclet](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html#standard-options-for-the-standard-doclet).
-- If you need more artifacts in the docletpath, you could use the
[<docletArtifacts/>](../javadoc-mojo.html#docletArtifacts) parameter.
-
-After executing `mvn site`, you will see that a UML graph (.dot file) will be
generated in the destination directory.
+-
[<additionalOptions/>](../javadoc-mojo.html${esc.hash}additionalOptions)
parameter could be used to set additional parameters on the command line,
specifically for doclet options.
+-
[<useStandardDocletOptions/>](../javadoc-mojo.html${esc.hash}useStandardDocletOptions)
parameter could be used to specify that the given doclet should use the
[options provided by the Standard
Doclet](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html#standard-options-for-the-standard-doclet).
+- If you need more artifacts in the docletpath, you could use the
[<docletArtifacts/>](../javadoc-mojo.html${esc.hash}docletArtifacts)
parameter.
+- A doclet must implement the `jdk.javadoc.doclet` API. Doclets written for
the old `com.sun.javadoc` API, such as
+ UmlGraph 5.x and DocCheck, do not run with current JDKs: that API was
removed in JDK 13.
# Using Alternate Doclet In Addition To The Javadoc Doclet
-To generate output from an alternate doclet in addition to the normal HTML
Javadoc doclet, add configuration similar to the following to your POM.
-
-In this example, the doclet is Sun DocCheck
([http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html/](http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html/)).
The Sun Doc Check Doclet is an extension to the Javadoc tool. It runs on
source code and reviews documentation comments, generating an HTML report that
identifies empty comments and other omissions and irregularities in the
documentation comments.
+To generate output from an alternate doclet in addition to the normal HTML
Javadoc, keep the default configuration
+and add an execution of the `javadoc` goal that runs the other doclet and
writes to its own
+[<outputDirectory/>](../javadoc-mojo.html${esc.hash}outputDirectory):
```xml
<project>
...
- <reporting>
+ <build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
- <reportSets>
- <reportSet>
- <id>html</id>
- <reports>
- <report>javadoc</report>
- </reports>
- </reportSet>
- <reportSet>
- <id>doccheck</id>
+ <executions>
+ <execution>
+ <id>uml</id>
+ <goals>
+ <goal>javadoc</goal>
+ </goals>
+ <phase>package</phase>
<configuration>
- <doclet>com.sun.tools.doclets.doccheck.DocCheck</doclet>
-
- <!-- <docletPath>/path/to/doccheck.jar</docletPath> -->
+ <doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
<docletArtifact>
- <groupId>com.sun.tools.doclets</groupId>
- <artifactId>doccheck</artifactId>
- <version>1.2b2</version>
+ <groupId>nl.talsmasoftware</groupId>
+ <artifactId>umldoclet</artifactId>
+ <version>2.2.1</version>
</docletArtifact>
- <additionalOptions>
- <additionalOption>-d</additionalOption>
-
<additionalOption>${esc.d}{project.build.directory}/site/doccheck</additionalOption>
- </additionalOptions>
-
- <!-- For the project-reports page-->
- <name>DocCheck</name>
- <description>DocCheck documentation.</description>
+
<outputDirectory>${esc.d}{project.build.directory}/uml</outputDirectory>
</configuration>
- <reports>
- <report>javadoc</report>
- </reports>
- </reportSet>
- </reportSets>
+ </execution>
+ </executions>
</plugin>
...
</plugins>
- </reporting>
+ </build>
...
</project>
```
+
+`mvn package javadoc:javadoc` then writes the alternate output to
`target/uml/apidocs` and the normal Javadoc to
+`target/reports/apidocs`.
diff --git a/src/site/markdown/examples/alternate-javadoc-tool.md.vm
b/src/site/markdown/examples/alternate-javadoc-tool.md.vm
index 2cf480cb..2ac36d15 100644
--- a/src/site/markdown/examples/alternate-javadoc-tool.md.vm
+++ b/src/site/markdown/examples/alternate-javadoc-tool.md.vm
@@ -26,12 +26,71 @@ under the License.
# Using Alternate Javadoc Tool
+By default, the Maven Javadoc Plugin runs the Javadoc tool of the JDK that
runs Maven: it looks for the `javadoc`
+executable under the Java property _java.home_, then under the environment
variable _JAVA_HOME_. To build the
+documentation with another JDK, select it with a toolchain or give the path of
its `javadoc` executable.
+
+Using a Toolchain
+-----------------
+
+The [<jdkToolchain/>](../javadoc-mojo.html${esc.hash}jdkToolchain)
parameter selects a JDK from your
+`~/.m2/toolchains.xml`, so the POM stays the same on every machine. It
overrides a toolchain selected by the
+maven-toolchains-plugin. For example, with this toolchain:
+
+```xml
+<toolchains>
+ <toolchain>
+ <type>jdk</type>
+ <provides>
+ <version>17</version>
+ </provides>
+ <configuration>
+ <jdkHome>/usr/lib/jvm/java-17-openjdk</jdkHome>
+ </configuration>
+ </toolchain>
+</toolchains>
+```
+
+and this configuration:
+
+```xml
+<project>
+ ...
+ <reporting> (or <build>)
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <jdkToolchain>
+ <version>17</version>
+ </jdkToolchain>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting> (or </build>)
+ ...
+</project>
+```
+
+the plugin logs the JDK it uses:
+
+```text
+[INFO] Toolchain in maven-javadoc-plugin: JDK[/usr/lib/jvm/java-17-openjdk]
+```
+
+See the [Guide to Using
Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html)
for more
+information.
+
Using Alternate Javadoc Executable
----------------------------------
-By default, the Maven Javadoc Plugin tries to auto-detect the Javadoc Tool
executable from the Java property _java.home_ or from the environment variable
_JAVA_HOME_.
-
-You could also specify the executable of the Javadoc Tool to use with the
[<javadocExecutable/>](../javadoc-mojo.html#javadocExecutable) parameter.
For example:
+You can also specify the executable of the Javadoc Tool to use with the
+[<javadocExecutable/>](../javadoc-mojo.html${esc.hash}javadocExecutable)
parameter. The path of the JDK `bin`
+directory is enough. For example:
```xml
<project>
@@ -43,7 +102,7 @@ You could also specify the executable of the Javadoc Tool to
use with the [<j
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
+
<javadocExecutable>${esc.d}{env.JAVA_17_HOME}/bin/javadoc</javadocExecutable>
...
</configuration>
</plugin>
@@ -54,14 +113,16 @@ You could also specify the executable of the Javadoc Tool
to use with the [<j
</project>
```
-**IMPORTANT NOTE**: by using
[<javadocExecutable/>](../javadoc-mojo.html#javadocExecutable) parameter,
the build will be platform dependent! A good practice is to define an
environment variable (e.g. JAVA_1.6_HOME), so you could specify it: (e.g.
<javadocExecutable>${esc.d}{env.JAVA_1.6_HOME}/bin/javadoc</javadocExecutable>).
An other ways is to define a POM property using
<project><properties/></project>.
+**IMPORTANT NOTE**: a literal path in
[<javadocExecutable/>](../javadoc-mojo.html${esc.hash}javadocExecutable)
+makes the build depend on one machine. Use an environment variable, as above,
or a POM property, or use a
+toolchain instead.
Using Alternate Javadoc Version
-------------------------------
-In the same way, the Maven Javadoc Plugin tries to auto-detect the Javadoc
Tool version by calling _javadoc -J-fullversion_.
+The Maven Javadoc Plugin detects the version of the Javadoc Tool by calling
_javadoc -J-version_.
-You could also specify the version of the Javadoc Tool executable. For example:
+You can also specify the version of the Javadoc Tool executable. For example:
```xml
<project>
@@ -73,7 +134,7 @@ You could also specify the version of the Javadoc Tool
executable. For example:
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <javadocVersion>1.5</javadocVersion>
+ <javadocVersion>17</javadocVersion>
...
</configuration>
</plugin>
@@ -84,4 +145,9 @@ You could also specify the version of the Javadoc Tool
executable. For example:
</project>
```
-**Note**: You could have a warning if the _javadocVersion_ specified is not
the same that the Javadoc Tool executable.
+**Note**: If the _javadocVersion_ you specify differs from the version of the
Javadoc Tool executable, the plugin
+logs a warning such as:
+
+```text
+[WARNING] Are you sure about the <javadocVersion/> parameter? It seems to be
21.0.13
+```
diff --git a/src/site/markdown/examples/javadoc-resources.md.vm
b/src/site/markdown/examples/javadoc-resources.md.vm
index 262c287d..663efe71 100644
--- a/src/site/markdown/examples/javadoc-resources.md.vm
+++ b/src/site/markdown/examples/javadoc-resources.md.vm
@@ -102,7 +102,7 @@ Package Comment File: _package.html_
These contain package comments. The _package.html_ is a brief summary of each
packages in the list of all packages.
-For more information, see [Documentation Comment
Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#documentation-comments)
and [ How to Write Doc Comments for the Javadoc Tool, Package-Level
Comments](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments).
+For more information, see [Documentation Comment
Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#documentation-comments).
Here is an example of a _package.html_ file, located in
_${esc.d}{basedir}/src/main/javadoc/org/apache/myapp/package.html_:
@@ -119,7 +119,7 @@ Here is an example of a _package.html_ file, located in
_${esc.d}{basedir}/src/m
</HTML>
```
-**Note**: With Javadoc 5.0, this file becomes _package-info.java_ and is
preferred over _package.html_.
+**Note**: Since Java 5, a _package-info.java_ file is preferred over
_package.html_.
For more information, see [Documentation Comment
Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#documentation-comments).
@@ -136,11 +136,11 @@ package org.apache.myapp;
Miscellaneous Unprocessed Files: _doc-files_
--------------------------------------------
-These include images, sample source code, class files, applets, HTML files...
+These include images, sample source code, class files, HTML files...
-For more information, see [Documentation Comment
Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#documentation-comments)
and [How to Write Doc Comments for the Javadoc Tool, Including Images
](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#images).
+For more information, see [Documentation Comment
Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#documentation-comments).
-In addition to _doc-files_ directories, since 2.6.1, the specific
_src/main/javadoc/resources_ directory will be copied to the generated Javadoc
resources directory (i.e. _apidocs/resources_). This is usefull when you want
to overwite default Javadoc tool resources, like the default _inherit.gif_ to
one with a transparent background (See [GIF](../images/inherit.gif) or
[PSD](../images/inherit.psd)).
+In addition to _doc-files_ directories, since 2.6.1, the specific
_src/main/javadoc/resources_ directory will be copied to the generated Javadoc
resources directory (i.e. _apidocs/resources_). Use it to add files to the
resources of the generated documentation or to replace them.
Here is a sample javadoc comment to use _app.png_ image, located in
_${esc.d}{basedir}/src/main/javadoc/org/apache/myapp/doc-files_ directory:
diff --git a/src/site/markdown/examples/links-configuration.md.vm
b/src/site/markdown/examples/links-configuration.md.vm
index 59ad6eb0..7f9a3980 100644
--- a/src/site/markdown/examples/links-configuration.md.vm
+++ b/src/site/markdown/examples/links-configuration.md.vm
@@ -41,8 +41,8 @@ You can add cross reference links to external projects using
the [<links/>
<version>${project.version}</version>
<configuration>
<links>
- <link>http://commons.apache.org/dbcp/apidocs/</link>
- <link>http://commons.apache.org/fileupload/apidocs/</link>
+
<link>https://commons.apache.org/proper/commons-dbcp/apidocs/</link>
+
<link>https://commons.apache.org/proper/commons-lang/apidocs/</link>
</links>
...
</configuration>
@@ -55,7 +55,7 @@ You can add cross reference links to external projects using
the [<links/>
**Important Note**: according the [Javadoc
specifications](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html#option-link),
all given links **should** have a fetchable `/package-list` or `/element-list`
file.
-You can try to detect all Javadoc links for the project's dependencies. You
need to use the [<detectLinks/>](../javadoc-mojo.html#detectLinks)
parameter. Detected links are based on the default Maven conventions. For
instance, if your project has a dependency on [Apache Commons
Lang](https://commons.apache.org/lang/) such as:
+You can try to detect all Javadoc links for the project's dependencies. You
need to use the [<detectLinks/>](../javadoc-mojo.html#detectLinks)
parameter. Detected links are based on the default Maven conventions. For
instance, if your project has a dependency on [Apache Commons
Lang](https://commons.apache.org/proper/commons-lang/) such as:
```xml
<project>
@@ -64,25 +64,25 @@ You can try to detect all Javadoc links for the project's
dependencies. You need
<dependency>
<groupId>commons-lang</groupId>
<artifactId>commons-lang</artifactId>
- <versions>2.4</version>
+ <version>2.6</version>
</dependency>
</dependencies>
...
</project>
```
-The added Javadoc link will be
[https://commons.apache.org/lang/apidocs](https://commons.apache.org/lang/apidocs).
+The added Javadoc link is the `<url/>` of the dependency's POM followed by
`/apidocs`, here `http://commons.apache.org/lang/apidocs`.
-A Javadoc API link, depending the JDK version used by your project, will be
added. The version of the Javadoc API is detected from the value of the
[<source/>](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#source)
parameter in the
[`org.apache.maven.plugins:maven-compiler-plugin`](http://maven.apache.org/plugins/maven-compiler-plugin)
(defined in ${esc.d}{project.build.plugins} or in
${esc.d}{project.build.pluginManagement}), or computed via the Javadoc T [...]
+A link to the Java SE API documentation is added for the Java version of your
project. The plugin takes that version from its
[<release/>](../javadoc-mojo.html#release) parameter (the
`maven.compiler.release` property), then from its
[<source/>](../javadoc-mojo.html#source) parameter (the
`maven.compiler.source` property), then from the
[<source/>](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#source)
parameter of the [`org.apache.maven.plugin [...]
-**Note**: if you are using an unsupported JDK like 7.0, you can add its
Javadoc API URL using the
[<javaApiLinks/>](../javadoc-mojo.html#javaApiLinks) parameter. For
example:
+**Note**: to link to another copy of the Java SE API documentation, for
example an internal mirror, set its URL with the
[<javaApiLinks/>](../javadoc-mojo.html#javaApiLinks) parameter. The key
is `api_` followed by the Java version (`api_11`; `api_1.8` for Java 8). For
example:
```xml
<configuration>
<javaApiLinks>
<property>
- <name>api_1.7</name>
- <value>http://download.java.net/jdk7/docs/api/</value>
+ <name>api_11</name>
+ <value>https://docs.example.com/jdk11/api/</value>
</property>
</javaApiLinks>
...
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 1bbe1e0b..302700bb 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -46,10 +46,10 @@ under the License.
### What are the Javadoc options supported by the Maven Javadoc Plugin?
-All options provided by Oracle on the Javadoc homepages are wrapped in the
Maven Javadoc Plugin. This plugin
-supports Javadoc 1.4, 1.5 and 6.0 options. Refer to the
-[Javadoc Package
Summary](./apidocs/org/apache/maven/plugins/javadoc/package-summary.html) for
more
-information and to the [Javadoc Plugin Documentation](./javadoc-mojo.html).
+Most options of the [Javadoc
tool](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html) and
+its Standard Doclet have a plugin parameter of the same name; the
+[Javadoc Plugin Documentation](./javadoc-mojo.html) lists them. Pass any other
option with the
+[*<additionalOptions/>*](./javadoc-mojo.html#additionalOptions)
parameter.
<a id="Where_in_the_pom.xml_do_I_configure_the_Javadoc_Plugin"></a>
@@ -62,7 +62,7 @@ You could also configure it in the *<plugins/>* or
*<pluginsManagement/
of your pom.xml. In this case, you will need to call `mvn javadoc:javadoc` to
run the main report.
**IMPORTANT NOTE**: using *<reporting/>* or *<build/>* elements
have not the same behavior, refer
-to [Using the <reporting/> Tag VS <build/>
Tag](http://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag)
+to [Using the <reporting/> Tag VS <build/>
Tag](https://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag)
part for more information.
<a id="Where_do_I_put_javadoc_resources_like_HTML_files_or_images"></a>
@@ -79,18 +79,19 @@ See [Using Javadoc
Resources](examples/javadoc-resources.html) for more informat
The Javadoc Plugin calls the Javadoc tool with
[argument
files](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javac.html#command-line-argument-files),
-i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk
< 1.4):
+i.e. files called 'options', 'packages' and 'argfile':
```
-javadoc.exe(or .sh) @options @packages | @argfile
+javadoc @options @packages | @argfile
```
These argument files are generated at runtime depending the Javadoc Plugin
configuration and are deleted when
the Javadoc Plugin ended.
-To preserve them, just add <debug>true</debug> in your Javadoc
Plugin configuration or just call
-`mvn javadoc:javadoc -Ddebug=true` or `mvn javadoc:javadoc -X`. In this case,
an additional script file
-(javadoc.bat (or .sh) will be created in the `apidocs` directory.
+To preserve them, add <debug>true</debug> to your Javadoc Plugin
configuration or call
+`mvn javadoc:javadoc -Ddebug=true`. The plugin then also writes a `javadoc.sh`
(`javadoc.bat` on Windows) script
+with the complete command line to the output directory,
`target/reports/apidocs` for `javadoc:javadoc`.
+`mvn javadoc:javadoc -X` logs the command line but deletes the files.
<a id="How_to_add_additional_Javadoc_parameters"></a>
@@ -111,7 +112,7 @@ Javadoc Plugin configuration.
The Javadoc Plugin calls the Javadoc tool with J options, e.g.:
```
-${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
+javadoc \
-J-Xss128m \
@options \
@packages | @argfile
@@ -167,7 +168,7 @@ To specify a proxy in the Javadoc tool, you need to
configure an active proxy in
<port>3128</port>
<username>foo</username>
<password>bar</password>
- <nonProxyHosts>java.sun.com|*.somewhere.com</nonProxyHosts>
+ <nonProxyHosts>localhost|*.somewhere.com</nonProxyHosts>
</proxy>
</proxies>
...
@@ -177,17 +178,18 @@ To specify a proxy in the Javadoc tool, you need to
configure an active proxy in
With this, the Javadoc tool will be called with networking J options, e.g.:
```
-${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
- -J-Dhttp.proxySet=true \
+javadoc \
-J-Dhttp.proxyHost=proxy.somewhere.com \
-J-Dhttp.proxyPort=3128 \
- -J-Dhttp.nonProxyHosts="java.sun.com|*.somewhere.com" \
- -J-Dhttp.proxyUser="foo" \
- -J-Dhttp.proxyPassword="bar" \
+ -J-Dhttps.proxyHost=proxy.somewhere.com \
+ -J-Dhttps.proxyPort=3128 \
+ "-J-Dhttp.nonProxyHosts=\"localhost^|*.somewhere.com\"" \
@options \
@packages | @argfile
```
+The proxy user name and password are not passed to the Javadoc tool.
+
**Note**: If your proxy needs more JVM
[networking
properties](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/doc-files/net-properties.html)
(like
NTLM), you could always add JVM options using the *<additionalJOption/>*
parameter in your Javadoc
@@ -259,7 +261,7 @@ mvn deploy:deploy-file \
-Dfile=<path-to-file> \
-Dpackaging=jar \
-DrepositoryId=<repository-id> \
- -Durl=dav:http://www.myrepository.com/m2 \
+ -Durl=https://repository.example.com/releases \
-Dclassifier=javadoc
```
@@ -267,10 +269,10 @@ mvn deploy:deploy-file \
### How to include additional source code directories in aggregate mode?
-If you use the Javadoc report in the aggregate mode, i.e. using the
`aggregate` parameter, and if the Javadoc
-report does not include additional source code directories defined using the
-[build-helper:add-source](https://www.mojohaus.org/build-helper-maven-plugin/add-source-mojo.html)
goal, you
-need to use the `javadoc:aggregate` goal instead of `javadoc:javadoc` goal.
Read the
+Use the `javadoc:aggregate` goal. It forks the `compile` phase of every
module, so it includes source
+directories added with the
+[build-helper:add-source](https://www.mojohaus.org/build-helper-maven-plugin/add-source-mojo.html)
goal. The
+`javadoc:javadoc` goal has no `aggregate` parameter any more. Read the
[Aggregating Javadocs for Multi-Projects](examples/aggregate.html) part for
more information.
<a id="How_to_use_links_option_in_Standard_Doclet"></a>
@@ -309,5 +311,5 @@ By default, these parameters have the following values:
### Why do I get errors when using links under Java 8?
-Due to [a bug in JDK 8](https://bugs.openjdk.java.net/browse/JDK-8040771) you
need at least Java 8u20 for this
+Due to [a bug in JDK 8](https://bugs.openjdk.org/browse/JDK-8040771) you need
at least Java 8u20 for this
to work. See
[MJAVADOC-393](https://issues.apache.org/jira/browse/MJAVADOC-393) for more
info.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md.vm
similarity index 70%
rename from src/site/markdown/index.md
rename to src/site/markdown/index.md.vm
index 87a2f92c..3616c1d2 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md.vm
@@ -27,21 +27,61 @@ under the License.
-->
# Apache Maven Javadoc Plugin
-The Javadoc Plugin uses the Javadoc tool to generate javadocs for the
specified project. For more information about the standard Javadoc tool, please
refer to [Reference
Guide](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html).
-The Javadoc Plugin gets the parameter values that will be used from the plugin
configuration specified in the pom. To hold all javadoc arguments, packages or
files, the Javadoc Plugin generates [argument
files](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javac.html#command-line-argument-files)
and calls the Javadoc tool as follows:
+The Javadoc Plugin runs the [Javadoc
tool](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javadoc.html) of
+your JDK to generate API documentation for a Maven project, packages that
documentation as a `javadoc` jar for
+deployment, and adds it to the project site as a report.
-```text
-javadoc.exe(or .sh) @options @packages | @argfile
-```
+The plugin requires Maven 3.9.0 or later and Java 8 or later. It uses the
`javadoc` executable of the JDK that runs
+Maven, unless you select another JDK with a
[toolchain](./examples/alternate-javadoc-tool.html).
-When no configuration values are set, the plugin sets default values instead
and then executes the Javadoc tool.
+${esc.h}${esc.h} Common Tasks
-You can also use the plugin to package the generated javadocs into a jar file
for distribution.
+- Generate the API documentation of a module into `target/reports/apidocs`:
-## Goals Overview
+ ```shell
+ mvn javadoc:javadoc
+ ```
-The Javadoc Plugin has 16 goals:
+- Attach a `-javadoc.jar` to every build, as Maven Central requires for a
release. Bind the `jar` goal in the
+ <build/> section of your POM and run `mvn verify` (or `mvn deploy`):
+
+ ```xml
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>attach-javadocs</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ```
+
+- Generate one set of API documentation for all modules of a multi-module
project, from the parent directory:
+
+ ```shell
+ mvn javadoc:aggregate
+ ```
+
+ See [Aggregating Javadocs for Multi-Projects](./examples/aggregate.html).
+
+- Add the API documentation to the project site: declare the plugin in the
<reporting/> section and run
+ `mvn site`. The documentation is written to `target/site/apidocs`. See the
[usage page](./usage.html).
+
+The plugin passes its configuration to the Javadoc tool in [argument
+files](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javac.html#command-line-argument-files)
and calls it as
+`javadoc @options @packages`, adding an `@argfile` for source files that it
passes one by one. To keep these files and
+a `javadoc.sh` (or `javadoc.bat`) script that repeats the call, run with
`-Ddebug=true`; see the
+[FAQ](./faq.html${esc.hash}How_to_know_exactly_the_Javadoc_command_line).
+
+${esc.h}${esc.h} Goals Overview
+
+The Javadoc Plugin has 15 goals:
- [javadoc:javadoc](./javadoc-mojo.html) generates the Javadoc files for the
project. It executes the standard Javadoc tool and supports the parameters used
by the tool.
- [javadoc:test-javadoc](./test-javadoc-mojo.html) generates the test Javadoc
files for the project. It executes the standard Javadoc tool and supports the
parameters used by the tool.
@@ -49,7 +89,7 @@ The Javadoc Plugin has 16 goals:
- [javadoc:test-javadoc-no-fork](./test-javadoc-no-fork-mojo.html) generates
the test Javadoc files for the project. It executes the standard Javadoc tool
and supports the parameters used by the tool without forking the
`generate-test-sources` phase again. Note that this goal does require
generation of test sources before site generation, e.g. by invoking `mvn clean
deploy site`.
- [javadoc:aggregate](./aggregate-mojo.html) generates the Javadoc files for
an aggregator project. It executes the standard Javadoc tool and supports the
parameters used by the tool.
- [javadoc:test-aggregate](./test-aggregate-mojo.html) generates the test
Javadoc files for an aggregator project. It executes the standard Javadoc tool
and supports the parameters used by the tool.
-- [javadoc:aggregate-no-fork](./aggregate-no-fork-mojo.html) generates the
Javadoc files for an aggregator project. It executes the standard Javadoc tool
and supports the parameters used by the tool without forking the
**compile**> phase again. Note that this goal does require generation of
class files before site generation, e.g. by invoking `mvn compile` or `mvn
install`.
+- [javadoc:aggregate-no-fork](./aggregate-no-fork-mojo.html) generates the
Javadoc files for an aggregator project. It executes the standard Javadoc tool
and supports the parameters used by the tool without forking the `compile`
phase again. Note that this goal does require generation of class files before
site generation, e.g. by invoking `mvn compile` or `mvn install`.
- [javadoc:test-aggregate-no-fork](./test-aggregate-no-fork-mojo.html)
generates the test Javadoc files for an aggregator project. It executes the
standard Javadoc tool and supports the parameters used by the tool without
forking the `compile` phase again. Note that this goal does require generation
of test class files before site generation, e.g. by invoking `mvn test-compile`
or `mvn install`.
- [javadoc:jar](./jar-mojo.html) creates an archive file of the generated
Javadocs. It is used during the release process to create the Javadoc artifact
for the project's release. This artifact is uploaded to the remote repository
along with the project's compiled binary and source archive.
- [javadoc:test-jar](./test-jar-mojo.html) creates an archive file of the
generated Test Javadocs.
@@ -57,15 +97,17 @@ The Javadoc Plugin has 16 goals:
- [javadoc:test-aggregate-jar](./test-aggregate-jar-mojo.html) creates an
archive file of the generated Test Javadocs for an aggregator project.
- [javadoc:resource-bundle](./resource-bundle-mojo.html) bundles the
`javadocDirectory` along with Javadoc configuration options such as taglet,
doclet, and link information into a deployable artifact.
- [javadoc:test-resource-bundle](./test-resource-bundle-mojo.html) bundles the
`testJavadocDirectory` along with Javadoc configuration options such as taglet,
doclet, and link information into a deployable artifact.
-## Usage
+- [javadoc:help](./help-mojo.html) displays help information on the plugin.
Run `mvn javadoc:help -Ddetail=true -Dgoal=<goal-name>` to display the
parameters of a goal.
+
+${esc.h}${esc.h} Usage
General instructions on how to use the Javadoc Plugin can be found on the
[usage page](./usage.html). Some more specific use cases are described in the
examples given below.
In case you still have questions regarding the plugin's usage, please have a
look at the [FAQ](./faq.html) and feel free to contact the [user mailing
list](./mailing-lists.html). The posts to the mailing list are archived and
could already contain the answer to your question as part of an older thread.
Hence, it is also worth browsing/searching the [mail
archive](./mailing-lists.html).
-If you feel like the plugin is missing a feature or has a defect, you can fill
a feature request or bug report in our [issue
tracker](./issue-management.html). When creating a new issue, please provide a
comprehensive description of your concern. Especially for fixing bugs it is
crucial that the developers can reproduce your problem. For this reason, entire
debug logs, POMs or most preferably little demo projects attached to the issue
are very much appreciated. Of course, patches are wel [...]
+If you feel like the plugin is missing a feature or has a defect, you can fill
a feature request or bug report in our [issue
tracker](./issue-management.html). When creating a new issue, please provide a
comprehensive description of your concern. Especially for fixing bugs it is
crucial that the developers can reproduce your problem. For this reason, entire
debug logs, POMs or most preferably little demo projects attached to the issue
are very much appreciated. Of course, patches are wel [...]
-## Examples
+${esc.h}${esc.h} Examples
The following examples show how to use the Javadoc Plugin in more advanced use
cases:
@@ -83,5 +125,6 @@ The following examples show how to use the Javadoc Plugin in
more advanced use c
- [Configuring Links](./examples/links-configuration.html)
- [Generating test Javadocs](./examples/test-javadocs.html)
- [Selective Javadocs Reports](./examples/selective-javadocs-report.html)
+- [Adding Additional Dependencies](./examples/additional-dependencies.html)
- [Generate Javadoc without duplicate execution of phase
generate-sources](./examples/javadoc-nofork.html)
- [Generate aggregate Javadocs without execution of phase
compile](./examples/aggregate-nofork.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index af3cf902..38ec3fb2 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -103,7 +103,7 @@ The Javadoc Plugin supports a large number of configuration
parameters. Each con
Please refer to the [Javadoc Plugin Documentation](./javadoc-mojo.html) for a
listing of these parameters. Most of these parameters are passed directly to
the Javadoc tool itself.
-**IMPORTANT NOTE**: configuring the Javadoc plugin in the <reporting/>
or <build/> elements in the pom have **NOT** the same behavior as
described in the [Guide to Configuring
Plug-ins](http://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag).
+**IMPORTANT NOTE**: configuring the Javadoc plugin in the <reporting/>
or <build/> elements in the pom have **NOT** the same behavior as
described in the [Guide to Configuring
Plug-ins](https://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag).
For instance, if you have the following snippet:
diff --git a/src/site/site.xml b/src/site/site.xml
index 7b52a2db..1ae9134b 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,7 +32,7 @@ under the License.
<item name="Usage" href="usage.html"/>
<item name="FAQ" href="faq.html"/>
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
- <item name="License" href="http://www.apache.org/licenses/"/>
+ <item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>
<menu name="Examples">