<?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 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 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 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>&lt;reporting/&gt;</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>&lt;plugins/&gt;</i> or <i>&lt;pluginsManagement/&gt;</i> in
          <i>&lt;build/&gt;</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>&lt;reporting/&gt;</i> or <i>&lt;build/&gt;</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 &lt;reporting/&gt; Tag VS &lt;build/&gt; 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="http://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 &lt; 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 &lt;debug&gt;true&lt;/debug&gt; 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>&lt;additionalOptions/&gt;</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>&lt;additionalJOption/&gt;</i> parameter
          in your Javadoc Plugin configuration.
        </p>
        <p>
          The Javadoc Plugin calls the Javadoc tool with J options, i.e.:
          <source><![CDATA[
${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>&lt;minmemory/&gt;</i> and
          <i>&lt;maxmemory/&gt;</i> parameters in your Javadoc Plugin configuration. For instance:
          <source><![CDATA[
<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>${user.home}/.m2/settings.xml</i>, similar to:
          <source><![CDATA[
<settings>
  ...
  <proxies>
   <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>3128</port>
      <username>foo</username>
      <password>bar</password>
      <nonProxyHosts>java.sun.com|*.somewhere.com</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>
]]></source>
          With this, the Javadoc tool will be called with networking J options, i.e.:
          <source><![CDATA[
${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
    -J-Dhttp.proxySet=true \
    -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" \
    @options \
    @packages | @argfile]]></source>
        </p>
        <p>
          <b>Note</b>: If your proxy needs more JVM
          <a href="http://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>&lt;additionalJOption/&gt;</i> parameter
          in your Javadoc Plugin configuration, i.e.:
          <source><![CDATA[
<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>&lt;quiet/&gt;</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>&lt;reportSets/&gt;</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><![CDATA[
<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><![CDATA[
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 <code>&lt;links/&gt;</code> option in Standard Doclet?</question>
      <answer>
        <p>
          You need to configure the <i><a href="./javadoc-mojo.html#links">&lt;links/&gt;</a></i> parameter. Also, you
          should correctly write references in your Javadoc, i.e.:
        </p>
        <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>
      </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="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>.
        </p>
        <div id="_6219854" style="display:none">
          <source><![CDATA[
...
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] An error has occurred in Javadoc report generation:Exit code: 1 - java.lang.IllegalArgumentException
  at sun.net.www.ParseUtil.decode(ParseUtil.java:189)
  at sun.misc.URLClassPath$FileLoader.&lt;init&gt;(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>
          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>&lt;encoding/&gt;</code>, <code>&lt;docencoding/&gt;</code> and <code>&lt;charset/&gt;</code> parameters?</question>
      <answer>
        <p>
          By default, these parameters have the following values:
        </p>
        <dl>
          <dt><code>&lt;encoding/&gt;</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>&lt;docencoding/&gt;</code></dt>
          <dd>Value of <code>${project.reporting.outputEncoding}</code> property or <code>UTF-8</code> if not specified.</dd>
          <dt><code>&lt;charset/&gt;</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>
