| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <faqs 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 Sun on the Javadoc homepages are wrapped in the Maven Javadoc Plugin. This |
| plugin supports Javadoc 1.4, 1.5 and 6.0 options. Refer you to the |
| <a href="./apidocs/org/apache/maven/plugin/javadoc/package-summary.html">Javadoc Package Summary</a> |
| for more information. |
| </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 site report 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 <plugins/> or <pluginsManagement/> in <build/> tag |
| of your pom.xml. In this case, you will need to call <code>mvn javadoc:javadoc</code> to run the main |
| report. |
| </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="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#argumentfiles">argument files</a>, |
| i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk < 1.4): |
| <source> |
| ${project.reporting.outputDirectory}/apidocs/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><additionalparam/></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 process 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, i.e.: |
| <source> |
| ${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> |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <configuration> |
| ... |
| <minmemory>128m</minmemory> |
| <maxmemory>1g</maxmemory> |
| ... |
| </configuration> |
| </plugin> |
| </plugins> |
| ... |
| </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>settings.xml</i>. Read the |
| <a href="http://maven.apache.org/guides/mini/guide-proxies.html">Configuring a proxy</a> guide for more information. |
| </p> |
| <p> |
| The Javadoc Plugin calls the Javadoc tool with networking J options, i.e.: |
| <source> |
| ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \ |
| -J-Dhttp.proxySet=true \ |
| -J-Dhttp.proxyHost=http://localhost \ |
| -J-Dhttp.proxyPort=80 \ |
| -J-Dhttp.nonProxyHosts="www.google.com|*.somewhere.com" \ |
| -J-Dhttp.proxyUser="toto" \ |
| -J-Dhttp.proxyPassword="toto" \ |
| @options \ |
| @packages | @argfile</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> |
| <project> |
| ... |
| <profiles> |
| <profile> |
| <id>release</id> |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <executions> |
| <execution> |
| <id>attach-javadocs</id> |
| <goals> |
| <goal>jar</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| </profile> |
| ... |
| </profiles> |
| ... |
| </project></source> |
| </p> |
| <p> |
| To deploy the Javadoc jar on a given Maven repository, you could call: |
| <source> |
| mvn deploy:deploy-file \ |
| -DgroupId=<group-id> \ |
| -DartifactId=<artifact-id> \ |
| -Dversion=<version> \ |
| -Dfile=<path-to-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="http://mojo.codehaus.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 links option in Standard Doclet?</question> |
| <answer> |
| <p> |
| You need to configure the <i><links/></i> parameter. Also, you need to correctly write references in |
| your Javadoc, i.e.: |
| <ul> |
| <li><code>@see MyMojo</code> or <code>{@link MyMojo}</code> will <b>NOT work</b>.</li> |
| <li><code>@see com.mycompany.plugin.myplugin.MyMojo</code> or <code>{@link com.mycompany.myplugin.MyMojo}</code> will <b>work</b>.</li> |
| </ul> |
| </p> |
| </answer> |
| </faq> |
| <faq id="On Windows with Sun JDK, why javadoc:javadoc goal blows up due to an IllegalArgumentException in sun.net.www.ParseUtil.decode()"> |
| <question>On Windows with Sun JDK, why <i>javadoc:javadoc</i> goal blows up due to an IllegalArgumentException in <i>sun.net.www.ParseUtil.decode()</i>?</question> |
| <answer> |
| <p> |
| You are on Windows XP with Sun JDK 5 or JDK 6 freshly installed, and when you run <i>mvn javadoc:javadoc</i>, |
| you are stick by an <i>sun.net.www.ParseUtil.decode()</i> exception like this |
| <a href="javascript:;" onclick="toggleException( '_6219854' );" style="cursor: pointer;vertical-align:text-bottom;">one</a>. |
| <div id="_6219854" style="display:none"> |
| <source> |
| ... |
| [INFO] ------------------------------------------------------------------------ |
| [ERROR] BUILD ERROR |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] An error has occurred in JavaDocs report generation:Exit code: 1 - java.lang.IllegalArgumentException |
| at sun.net.www.ParseUtil.decode(ParseUtil.java:189) |
| at sun.misc.URLClassPath$FileLoader.<init>(URLClassPath.java:953) |
| at sun.misc.URLClassPath$3.run(URLClassPath.java:326) |
| at java.security.AccessController.doPrivileged(Native Method) |
| at sun.misc.URLClassPath.getLoader(URLClassPath.java:320) |
| at sun.misc.URLClassPath.getLoader(URLClassPath.java:297) |
| at sun.misc.URLClassPath.findResource(URLClassPath.java:144) |
| at java.net.URLClassLoader$2.run(URLClassLoader.java:362) |
| at java.security.AccessController.doPrivileged(Native Method) |
| at java.net.URLClassLoader.findResource(URLClassLoader.java:359) |
| at java.lang.ClassLoader.getResource(ClassLoader.java:977) |
| at java.lang.ClassLoader.getResourceAsStream(ClassLoader.java:1159) |
| at javax.xml.parsers.SecuritySupport$4.run(SecuritySupport.java:96) |
| at java.security.AccessController.doPrivileged(Native Method) |
| at javax.xml.parsers.SecuritySupport.getResourceAsStream(SecuritySupport.java:89) |
| at javax.xml.parsers.FactoryFinder.findJarServiceProvider(FactoryFinder.java:250) |
| at javax.xml.parsers.FactoryFinder.find(FactoryFinder.java:223) |
| at javax.xml.parsers.SAXParserFactory.newInstance(SAXParserFactory.java:128) |
| at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:72) |
| at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108) |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) |
| at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) |
| at java.lang.reflect.Method.invoke(Method.java:597) |
| at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) |
| at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) |
| at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) |
| at com.sun.tools.javadoc.Start.begin(Start.java:128) |
| at com.sun.tools.javadoc.Main.execute(Main.java:41) |
| at com.sun.tools.javadoc.Main.main(Main.java:31) |
| com.sun.tools.doclets.internal.toolkit.util.DocletAbortException |
| at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:79) |
| at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108) |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) |
| at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) |
| at java.lang.reflect.Method.invoke(Method.java:597) |
| at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) |
| at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) |
| at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) |
| at com.sun.tools.javadoc.Start.begin(Start.java:128) |
| at com.sun.tools.javadoc.Main.execute(Main.java:41) |
| at com.sun.tools.javadoc.Main.main(Main.java:31) |
| com.sun.tools.doclets.internal.toolkit.util.DocletAbortException |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:159) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) |
| at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) |
| at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) |
| at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) |
| at java.lang.reflect.Method.invoke(Method.java:597) |
| at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) |
| at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) |
| at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) |
| at com.sun.tools.javadoc.Start.begin(Start.java:128) |
| at com.sun.tools.javadoc.Main.execute(Main.java:41) |
| at com.sun.tools.javadoc.Main.main(Main.java:31) |
| |
| Command line was:C:\Java\jdk1.6.0_03\jre\..\bin\javadoc.exe @options @packages |
| ...</source> |
| </div> |
| </p> |
| <p> |
| Your <i>CLASSPATH</i> environement variable is probably corrupted, i.e. something like: |
| <source>CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%</source> |
| with <code>%JAVAHOME%</code> not a valid environment variable. |
| </p> |
| <p> |
| To resolve it, just reset the <i>CLASSPATH</i> environement variable, i.e.: <source>set CLASSPATH=</source> |
| or set a new <i>CLASSPATH</i> environement variable, i.e.: |
| <source>set CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip</source> |
| or fix the wrong environment variable. |
| </p> |
| <p> |
| Refer you to |
| <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854">http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854</a> |
| from Sun for more details. |
| </p> |
| |
| <script language="javascript" type="text/javascript"> |
| function toggleException( divId ) |
| { |
| var div = document.getElementById( divId ); |
| if( div.style.display == '' ) |
| { |
| div.style.display = 'none'; |
| } |
| else |
| { |
| div.style.display = ''; |
| } |
| } |
| </script> |
| </answer> |
| </faq> |
| <faq id="What are the values of encoding, docencoding and charset parameters"> |
| <question>What are the values of <code>encoding</code>, <code>docencoding</code> and <code>charset</code> parameters?</question> |
| <answer> |
| <p> |
| By default, these parameters have the following values: |
| <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> |
| </p> |
| </answer> |
| </faq> |
| </part> |
| </faqs> |