You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/09 23:19:42 UTC
(maven-javadoc-plugin) branch faq-to-markdown created (now ed44ff32)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
at ed44ff32 Convert the FAQ from FML to Markdown
This branch includes the following new commits:
new 71c41e1c Rename the FAQ ahead of converting it
new ed44ff32 Convert the FAQ from FML to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-javadoc-plugin) 02/02: Convert the FAQ from FML to Markdown
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit ed44ff32ef649ec2ce0c6d0c66a0004856f502d8
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:19:33 2026 +0200
Convert the FAQ from FML to Markdown
doxia-converter cannot target FML usefully - the questions come out as
link-reference syntax rather than headings, the [top] back-links become
links to a nonexistent 'top' page, and the contents links lose their #
anchors. The page is written out by hand instead.
Every anchor on this page is one Doxia rewrites at render time: none of
the sixteen <faq id=…> values is a valid XML name, so DoxiaUtils.encodeId
turns 'What are the Javadoc options supported by the Maven Javadoc Plugin'
into #What_are_the_Javadoc_options_supported_by_the_Maven_Javadoc_Plugin,
and the comma in the encoding question into '.2C'. The <a name> elements
here reproduce those rendered forms, not the raw attributes, so the live
deep links still resolve.
Verified by building the site before and after and comparing the set of
anchors the generated faq.html actually serves. All sixteen, plus #top,
are still present, the <head> is byte-identical, and every link target on
the page is unchanged.
site.xml needs no edit: src/site/fml/faq.fml and
src/site/markdown/faq.md both render to faq.html.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written, which is the only rendering loss.
Generated-by: Claude Opus 5 (1M context)
---
src/site/markdown/faq.md | 444 ++++++++++++++++++++++-------------------------
1 file changed, 212 insertions(+), 232 deletions(-)
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index a9a1af7b..6daf35ea 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -1,4 +1,6 @@
-<?xml version="1.0" encoding="UTF-8"?>
+---
+title: Frequently Asked Questions
+---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,113 +21,110 @@ specific language governing permissions and limitations
under the License.
-->
+<a name="top"></a>
-<faqs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns="http://maven.apache.org/FML/1.0.1"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
- id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="What are the Javadoc options supported by the Maven Javadoc Plugin">
- <question>What are the Javadoc options supported by the Maven Javadoc Plugin?</question>
- <answer>
- <p>
- 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
- <a href="./apidocs/org/apache/maven/plugins/javadoc/package-summary.html">Javadoc Package Summary</a>
- for more information and to the <a href="./javadoc-mojo.html">Javadoc Plugin Documentation</a>.
- </p>
- </answer>
- </faq>
- <faq id="Where in the pom.xml do I configure the Javadoc Plugin">
- <question>Where in the pom.xml do I configure the Javadoc Plugin?</question>
- <answer>
- <p>
- Like all other reporting plugins, the Javadoc Plugin goes in the <i><reporting/></i> section
- of your pom.xml. In this case, you will need to call <code>mvn site</code> to run reports.
- </p>
- <p>
- You could also configure it in the <i><plugins/></i> or <i><pluginsManagement/></i> in
- <i><build/></i> tag of your pom.xml. In this case, you will need to call
- <code>mvn javadoc:javadoc</code> to run the main report.
- </p>
- <p>
- <b>IMPORTANT NOTE</b>: using <i><reporting/></i> or <i><build/></i> elements have not the same
- behavior, refer to
- <a href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag">Using the <reporting/> Tag VS <build/> Tag</a>
- part for more information.
- </p>
- </answer>
- </faq>
- <faq id="Where do I put javadoc resources like HTML files or images">
- <question>Where do I put Javadoc resources like HTML files or images?</question>
- <answer>
- <p>
- All javadoc resources like HTML files, images could be put in the
- <i>${basedir}/src/main/javadoc</i> directory.
- </p>
- <p>
- See <a href="examples/javadoc-resources.html">Using Javadoc Resources</a> for more information.
- </p>
- </answer>
- </faq>
- <faq id="How to know exactly the Javadoc command line">
- <question>How to know exactly the Javadoc command line?</question>
- <answer>
- <p>
- The Javadoc Plugin calls the Javadoc tool with
- <a href="https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles">argument files</a>,
- i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk < 1.4):
- <source><![CDATA[
-javadoc.exe(or .sh) @options @packages | @argfile]]></source>
- </p>
- <p>
- These argument files are generated at runtime depending the Javadoc Plugin configuration and are deleted
- when the Javadoc Plugin ended.
- </p>
- <p>
- To preserve them, just add <debug>true</debug> in your Javadoc Plugin configuration or just call
- <code>mvn javadoc:javadoc -Ddebug=true</code> or <code>mvn javadoc:javadoc -X</code>.
- In this case, an additional script file (javadoc.bat (or .sh) will be created in the <code>apidocs</code>
- directory.
- </p>
- </answer>
- </faq>
- <faq id="How to add additional Javadoc parameters">
- <question>How to add additional Javadoc parameters?</question>
- <answer>
- <p>
- You could need to add more Javadoc parameters to be process by the Javadoc Tool (i.e. for doclet).
- </p>
- <p>
- For this, you should use the <i><additionalOptions/></i> parameter in your Javadoc Plugin configuration.
- </p>
- </answer>
- </faq>
- <faq id="How to add additional Javadoc options">
- <question>How to add additional Javadoc options?</question>
- <answer>
- <p>
- You could need to add more J options (i.e. runtime system java options that runs Javadoc tool like -J-Xss)
- to be processed by the Javadoc Tool. For this, you should use the <i><additionalJOption/></i> parameter
- in your Javadoc Plugin configuration.
- </p>
- <p>
- The Javadoc Plugin calls the Javadoc tool with J options, e.g.:
- <source><
+2. [Where in the pom.xml do I configure the Javadoc Plugin?](#Where_in_the_pom.xml_do_I_configure_the_Javadoc_Plugin)
+3. [Where do I put Javadoc resources like HTML files or images?](#Where_do_I_put_javadoc_resources_like_HTML_files_or_images)
+4. [How to know exactly the Javadoc command line?](#How_to_know_exactly_the_Javadoc_command_line)
+5. [How to add additional Javadoc parameters?](#How_to_add_additional_Javadoc_parameters)
+6. [How to add additional Javadoc options?](#How_to_add_additional_Javadoc_options)
+7. [How to increase Javadoc heap size?](#How_to_increase_Javadoc_heap_size)
+8. [How to add proxy support?](#How_to_add_proxy_support)
+9. [How to have less output?](#How_to_have_less_output)
+10. [How to remove test Javadocs report?](#How_to_remove_test_Javadocs_report)
+11. [How to deploy Javadoc jar file?](#How_to_deploy_Javadoc_jar_file)
+12. [How to include additional source code directories in aggregate mode?](#How_to_include_additional_source_code_directories_in_aggregate_mode)
+13. [How to use `<links/>` option in Standard Doclet?](#How_to_use_links_option_in_Standard_Doclet)
+14. [How to add cross reference link to internal-external projects?](#How_to_add_cross_reference_link_to_internal-external_projects)
+15. [What are the values of the `<encoding/>`, `<docencoding/>`, and `<charset/>` parameters?](#What_are_the_values_of_the_encoding.2C_docencoding.2C_and_charset_parameters)
+16. [Why do I get errors when using links under Java 8?](#Why_do_I_get_errors_when_using_links_under_Java_8)
+
+<a name="What_are_the_Javadoc_options_supported_by_the_Maven_Javadoc_Plugin"></a>
+
+### 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).
+
+<a name="Where_in_the_pom.xml_do_I_configure_the_Javadoc_Plugin"></a>
+
+### Where in the pom.xml do I configure the Javadoc Plugin?
+
+Like all other reporting plugins, the Javadoc Plugin goes in the *<reporting/>* section of your pom.xml.
+In this case, you will need to call `mvn site` to run reports.
+
+You could also configure it in the *<plugins/>* or *<pluginsManagement/>* in *<build/>* tag
+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)
+part for more information.
+
+<a name="Where_do_I_put_javadoc_resources_like_HTML_files_or_images"></a>
+
+### Where do I put Javadoc resources like HTML files or images?
+
+All javadoc resources like HTML files, images could be put in the *${basedir}/src/main/javadoc* directory.
+
+See [Using Javadoc Resources](examples/javadoc-resources.html) for more information.
+
+<a name="How_to_know_exactly_the_Javadoc_command_line"></a>
+
+### How to know exactly the Javadoc command line?
+
+The Javadoc Plugin calls the Javadoc tool with
+[argument files](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles),
+i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk < 1.4):
+
+```
+javadoc.exe(or .sh) @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.
+
+<a name="How_to_add_additional_Javadoc_parameters"></a>
+
+### How to add additional Javadoc parameters?
+
+You could need to add more Javadoc parameters to be process by the Javadoc Tool (i.e. for doclet).
+
+For this, you should use the *<additionalOptions/>* parameter in your Javadoc Plugin configuration.
+
+<a name="How_to_add_additional_Javadoc_options"></a>
+
+### How to add additional Javadoc options?
+
+You could need to add more J options (i.e. runtime system java options that runs Javadoc tool like -J-Xss) to
+be processed by the Javadoc Tool. For this, you should use the *<additionalJOption/>* parameter in your
+Javadoc Plugin configuration.
+
+The Javadoc Plugin calls the Javadoc tool with J options, e.g.:
+
+```
${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
-J-Xss128m \
@options \
- @packages | @argfile]]></source>
- </p>
- </answer>
- </faq>
- <faq id="How to increase Javadoc heap size">
- <question>How to increase Javadoc heap size?</question>
- <answer>
- <p>
- If you need to increase the Javadoc heap size, you should use the <i><minmemory/></i> and
- <i><maxmemory/></i> parameters in your Javadoc Plugin configuration. For instance:
- <source><![CDATA[
+ @packages | @argfile
+```
+
+<a name="How_to_increase_Javadoc_heap_size"></a>
+
+### How to increase Javadoc heap size?
+
+If you need to increase the Javadoc heap size, you should use the *<minmemory/>* and
+*<maxmemory/>* parameters in your Javadoc Plugin configuration. For instance:
+
+```xml
<project>
...
<reporting>
@@ -144,22 +143,20 @@ ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
...
</reporting>
...
-</project>]]></source>
- </p>
- <p>
- <b>Note:</b> The memory unit depends on the JVM used. The units supported could be: <code>k</code>,
- <code>kb</code>, <code>m</code>, <code>mb</code>, <code>g</code>, <code>gb</code>, <code>t</code>,
- <code>tb</code>. If no unit specified, the default unit is <code>m</code>.
- </p>
- </answer>
- </faq>
- <faq id="How to add proxy support">
- <question>How to add proxy support?</question>
- <answer>
- <p>
- To specify a proxy in the Javadoc tool, you need to configure an active proxy in your
- <i>${user.home}/.m2/settings.xml</i>, similar to:
- <source><![CDATA[
+</project>
+```
+
+**Note:** The memory unit depends on the JVM used. The units supported could be: `k`, `kb`, `m`, `mb`, `g`,
+`gb`, `t`, `tb`. If no unit specified, the default unit is `m`.
+
+<a name="How_to_add_proxy_support"></a>
+
+### How to add proxy support?
+
+To specify a proxy in the Javadoc tool, you need to configure an active proxy in your
+*${user.home}/.m2/settings.xml*, similar to:
+
+```xml
<settings>
...
<proxies>
@@ -175,9 +172,11 @@ ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
</proxies>
...
</settings>
-]]></source>
- With this, the Javadoc tool will be called with networking J options, e.g.:
- <source><![CDATA[
+```
+
+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 \
-J-Dhttp.proxyHost=proxy.somewhere.com \
@@ -186,45 +185,42 @@ ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
-J-Dhttp.proxyUser="foo" \
-J-Dhttp.proxyPassword="bar" \
@options \
- @packages | @argfile]]></source>
- </p>
- <p>
- <b>Note</b>: If your proxy needs more JVM
- <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">networking properties</a>
- (like NTLM), you could always add JVM options using the <i><additionalJOption/></i> parameter
- in your Javadoc Plugin configuration, e.g.:
- <source>< (like
+NTLM), you could always add JVM options using the *<additionalJOption/>* parameter in your Javadoc
+Plugin configuration, e.g.:
+
+```xml
<configuration>
<additionalJOption>-J-Dhttp.auth.ntlm.domain=MYDOMAIN</additionalJOption>
...
-</configuration>]]></source>
- </p>
- </answer>
- </faq>
- <faq id="How to have less output">
- <question>How to have less output?</question>
- <answer>
- <p>
- Just set the <i><quiet/></i> parameter to <i>true</i> in your Javadoc Plugin configuration.
- </p>
- </answer>
- </faq>
- <faq id="How to remove test Javadocs report">
- <question>How to remove test Javadocs report?</question>
- <answer>
- <p>
- You need to configure the <i><reportSets/></i> parameter. Read the
- <a href="examples/selective-javadocs-report.html">Selective Javadocs Reports</a> part for more information.
- </p>
- </answer>
- </faq>
- <faq id="How to deploy Javadoc jar file">
- <question>How to deploy Javadoc jar file?</question>
- <answer>
- <p>
- Basically, you need to call <i>mvn clean javadoc:jar deploy</i>. If you want to include the javadoc jar
- in a release process, you need to attach it in the release profile, for instance:
- <source>< part for more information.
+
+<a name="How_to_deploy_Javadoc_jar_file"></a>
+
+### How to deploy Javadoc jar file?
+
+Basically, you need to call *mvn clean javadoc:jar deploy*. If you want to include the javadoc jar in a
+release process, you need to attach it in the release profile, for instance:
+
+```xml
<project>
...
<profiles>
@@ -250,11 +246,12 @@ ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
...
</profiles>
...
-</project>]]></source>
- </p>
- <p>
- To deploy the Javadoc jar on a given Maven repository, you could call:
- <source><![CDATA[
+</project>
+```
+
+To deploy the Javadoc jar on a given Maven repository, you could call:
+
+```
mvn deploy:deploy-file \
-DgroupId=<group-id> \
-DartifactId=<artifact-id> \
@@ -263,71 +260,54 @@ mvn deploy:deploy-file \
-Dpackaging=jar \
-DrepositoryId=<repository-id> \
-Durl=dav:http://www.myrepository.com/m2 \
- -Dclassifier=javadoc]]></source>
- </p>
- </answer>
- </faq>
- <faq id="How to include additional source code directories in aggregate mode">
- <question>How to include additional source code directories in aggregate mode?</question>
- <answer>
- <p>
- If you use the Javadoc report in the aggregate mode, i.e. using the <code>aggregate</code> parameter, and if the
- Javadoc report does not include additional source code directories defined using the
- <a href="https://www.mojohaus.org/build-helper-maven-plugin/add-source-mojo.html">build-helper:add-source</a> goal,
- you need to use the <code>javadoc:aggregate</code> goal instead of <code>javadoc:javadoc</code> goal. Read the
- <a href="examples/aggregate.html">Aggregating Javadocs for Multi-Projects</a> part for more information.
- </p>
- </answer>
- </faq>
- <faq id="How to use links option in Standard Doclet">
- <question>How to use <code><links/></code> option in Standard Doclet?</question>
- <answer>
- <p>
- You need to configure the <i><a href="./javadoc-mojo.html#links"><links/></a></i> parameter. Also, you
- should correctly write references in your Javadoc. That is,
- </p>
- <ul>
- <li><code>@see MyMojo</code> or <code>{@link MyMojo}</code> will <strong>NOT work</strong>.</li>
- <li><code>@see com.mycompany.plugin.myplugin.MyMojo</code> or <code>{@link com.mycompany.myplugin.MyMojo}</code>
- will <strong>work</strong>.</li>
- </ul>
- </answer>
- </faq>
- <faq id="How to add cross reference link to internal-external projects">
- <question>How to add cross reference link to internal-external projects?</question>
- <answer>
- <p>
- Please refer to <a href="./examples/links-configuration.html">Links configuration page</a>.
- </p>
- </answer>
- </faq>
- <faq id="What are the values of the encoding, docencoding, and charset parameters">
- <question>What are the values of the <code><encoding/></code>, <code><docencoding/></code>, and <code><charset/></code> parameters?</question>
- <answer>
- <p>
- By default, these parameters have the following values:
- </p>
- <dl>
- <dt><code><encoding/></code></dt>
- <dd>Value of <code>${project.build.sourceEncoding}</code> property or the value of the
- <code>file.encoding</code> system property if not specified.</dd>
- <dt><code><docencoding/></code></dt>
- <dd>Value of <code>${project.reporting.outputEncoding}</code> property or <code>UTF-8</code> if not specified.</dd>
- <dt><code><charset/></code></dt>
- <dd>Value of <code>docencoding</code> parameter if not specified.</dd>
- </dl>
- </answer>
- </faq>
- <faq id="Why do I get errors when using links under Java 8">
- <question>Why do I get errors when using links under Java 8?</question>
- <answer>
- <p>
- Due to <a href="https://bugs.openjdk.java.net/browse/JDK-8040771">a bug in JDK 8</a>
- you need at least Java 8u20 for this to work. See
- <a href="https://issues.apache.org/jira/browse/MJAVADOC-393">MJAVADOC-393</a>
- for more info.
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
+ -Dclassifier=javadoc
+```
+
+<a name="How_to_include_additional_source_code_directories_in_aggregate_mode"></a>
+
+### 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
+[Aggregating Javadocs for Multi-Projects](examples/aggregate.html) part for more information.
+
+<a name="How_to_use_links_option_in_Standard_Doclet"></a>
+
+### How to use `<links/>` option in Standard Doclet?
+
+You need to configure the [*<links/>*](./javadoc-mojo.html#links) parameter. Also, you should correctly
+write references in your Javadoc. That is,
+
+- `@see MyMojo` or `{@link MyMojo}` will **NOT work**.
+- `@see com.mycompany.plugin.myplugin.MyMojo` or `{@link com.mycompany.myplugin.MyMojo}` will **work**.
+
+<a name="How_to_add_cross_reference_link_to_internal-external_projects"></a>
+
+### How to add cross reference link to internal-external projects?
+
+Please refer to [Links configuration page](./examples/links-configuration.html).
+
+<a name="What_are_the_values_of_the_encoding.2C_docencoding.2C_and_charset_parameters"></a>
+
+### What are the values of the `<encoding/>`, `<docencoding/>`, and `<charset/>` parameters?
+
+By default, these parameters have the following values:
+
+`<encoding/>`
+: Value of `${project.build.sourceEncoding}` property or the value of the `file.encoding` system property if
+ not specified.
+
+`<docencoding/>`
+: Value of `${project.reporting.outputEncoding}` property or `UTF-8` if not specified.
+
+`<charset/>`
+: Value of `docencoding` parameter if not specified.
+
+<a name="Why_do_I_get_errors_when_using_links_under_Java_8"></a>
+
+### 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
+to work. See [MJAVADOC-393](https://issues.apache.org/jira/browse/MJAVADOC-393) for more info.
(maven-javadoc-plugin) 01/02: Rename the FAQ ahead of converting it
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit 71c41e1c854d51760e6044c3843b35b33c985eb6
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:17:58 2026 +0200
Rename the FAQ ahead of converting it
Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history. Please merge or rebase rather than squash.
Generated-by: Claude Opus 5 (1M context)
---
src/site/{fml/faq.fml => markdown/faq.md} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
diff --git a/src/site/fml/faq.fml b/src/site/markdown/faq.md
similarity index 100%
rename from src/site/fml/faq.fml
rename to src/site/markdown/faq.md