Unable to configure alternate Javadoc output directory

src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java

@@ -472,8 +472,9 @@ public AbstractJavadocMojo(
     protected boolean useStandardDocletOptions;
 
     /**
-     * Detect the Javadoc links for all dependencies defined in the project. The detection is based on the default
-     * Maven conventions, i.e.: <code>${project.url}/apidocs</code>.
+     * Detect the Javadoc links for all dependencies defined in the project. The detection is based
+     * on the default Maven conventions, i.e.: <code>${project.url}/${destDir}</code> with
+     * {@code destDir} from the Javadoc plugin configuration (<code>apidocs</code> by default).
      * <br/>
      * For instance, if the project has a dependency to
      * <a href="http://commons.apache.org/lang/">Apache Commons Lang</a> i.e.:
@@ -496,8 +497,10 @@ public AbstractJavadocMojo(
      * Detect the links for all modules defined in the project.
      * <br/>
      * If {@code reactorProjects} is defined in a non-aggregator way, it generates default offline links
-     * between modules based on the defined project's URLs. For instance, if a parent project has two projects
-     * <code>module1</code> and <code>module2</code>, the <code>-linkoffline</code> will be:
+     * between modules based on the defined project's URLs and {@code destDir}
+     * in the Javadoc plugin configuration (<code>apidocs</code> by default).
+     * For instance, if a parent project has two projects
+     * <code>module1</code> and <code>module2</code>, the <code>-linkoffline</code> will be by default:
      * <br/>
      * The added Javadoc <code>-linkoffline</code> parameter for <b>module1</b> will be
      * <code>/absolute/path/to/</code><b>module2</b><code>/target/site/apidocs</code>
@@ -1670,6 +1673,14 @@ public AbstractJavadocMojo(
     @Parameter(property = "maven.javadoc.disableNoFonts", defaultValue = "false")
     private boolean disableNoFonts;
 
+    /**
+     * The name of the destination directory.
+     *
+     * @since 2.1
+     */
+    @Parameter(property = "destDir", defaultValue = "apidocs")
+    protected String destDir;
+
     // ----------------------------------------------------------------------
     // protected methods
     // ----------------------------------------------------------------------
@@ -1705,7 +1716,7 @@ protected String getOutputDirectory() {
      * @return a String that contains the target directory
      */
     protected String getPluginReportOutputDirectory() {
-        return getOutputDirectory() + "/" + (isTest() ? "test" : "") + "apidocs";
+        return getOutputDirectory() + "/" + (isTest() ? "test" : "") + destDir;
     }
 
     protected MavenProject getProject() {
@@ -5326,7 +5337,8 @@ protected boolean isDetectOfflineLinks() {
     }
 
     /**
-     * Using Maven, a Javadoc link is given by <code>${project.url}/apidocs</code>.
+     * Using Maven, a Javadoc link is given by <code>${project.url}/${destDir}</code> with
+     * {@code destDir} from the Javadoc plugin configuration (<code>apidocs</code> by default).
      *
      * @return the detected Javadoc links using the Maven conventions for all modules defined in the current project
      *         or an empty list
@@ -5425,7 +5437,8 @@ private List<OfflineLink> getModulesLinks() throws MavenReportException {
     }
 
     /**
-     * Using Maven, a Javadoc link is given by <code>${project.url}/apidocs</code>.
+     * Using Maven, a Javadoc link is given by <code>${project.url}/${destDir}</code> with
+     * {@code destDir} from the Javadoc plugin configuration (<code>apidocs</code> by default).
      *
      * @return the detected Javadoc links using the Maven conventions for all dependencies defined in the current
      *         project or an empty list.
@@ -5678,7 +5691,6 @@ protected boolean isValidJavadocLink(String link, boolean detecting) {
             if (JavadocUtil.isValidPackageList(packageListUri.toURL(), settings, validateLinks)) {
                 return true;
             }
-
             if (getLog().isErrorEnabled()) {
                 if (detecting) {
                     getLog().warn("Invalid links: " + link + " with /" + PACKAGE_LIST + " or / " + ELEMENT_LIST
@@ -5756,7 +5768,9 @@ private boolean isJavadocVMInitError(String output) {
 
     /**
      * @param project not null
-     * @return the javadoc link based on the project URL i.e. <code>${project.url}/apidocs</code>.
+     * @return the javadoc link based on the project URL i.e. <code>${project.url}/${destDir}</code>
+     *         with {@code destDir} from the Javadoc plugin configuration (<code>apidocs</code> by
+     *         default).
      * @since 2.6
      */
     private static String getJavadocLink(MavenProject project) {
@@ -5765,8 +5779,14 @@ private static String getJavadocLink(MavenProject project) {
         }
 
         String url = cleanUrl(project.getUrl());
+        String destDir = "apidocs"; // see AbstractJavadocMojo#destDir
+        final String pluginId = "org.apache.maven.plugins:maven-javadoc-plugin";
+        String destDirConfigured = getPluginParameter(project, pluginId, "destDir");
+        if (destDirConfigured != null) {
+            destDir = destDirConfigured;
+        }
 
-        return url + "/apidocs";
+        return url + "/" + destDir;
     }
 
     /**

src/main/java/org/apache/maven/plugins/javadoc/JavadocReport.java

@@ -160,7 +160,7 @@ public String getOutputName() {
     /** {@inheritDoc} */
     @Override
     public String getOutputPath() {
-        return (isTest() ? "test" : "") + "apidocs" + "/index";
+        return (isTest() ? "test" : "") + destDir + "/index";
     }
 
     /** {@inheritDoc} */
@@ -275,7 +275,7 @@ public void setReportOutputDirectory(File reportOutputDirectory) {
     /** {@inheritDoc} */
     @Override
     protected String getPluginReportOutputDirectory() {
-        return getReportOutputDirectory().getAbsolutePath() + "/" + (isTest() ? "test" : "") + "apidocs";
+        return getReportOutputDirectory().getAbsolutePath() + "/" + (isTest() ? "test" : "") + destDir;
     }
 
     /** {@inheritDoc} */

src/main/java/org/apache/maven/plugins/javadoc/TestJavadocReport.java

@@ -263,16 +263,16 @@ private ResourceBundle getBundle(Locale locale) {
     }
 
     /**
-     * Add the <code>../apidocs</code> to the links parameter so Test report could be linked to the Main report.
+     * Add the <code>../${destDir}</code> to the links parameter so Test report could be linked to the Main report.
      */
     private void addMainJavadocLink() {
         if (links == null) {
             links = new ArrayList<>();
         }
 
-        File apidocs = new File(getReportOutputDirectory(), "apidocs");
-        if (apidocs.isDirectory() && !links.contains("../apidocs")) {
-            links.add("../apidocs");
+        File apidocs = new File(getReportOutputDirectory(), destDir);
+        if (apidocs.isDirectory() && !links.contains("../" + destDir)) {
+            links.add("../" + destDir);
         }
     }
 

src/site/apt/examples/output-configuration.apt.vm

@@ -0,0 +1,60 @@
+ ------
+ Using Alternative Output Directory
+ ------
+ Vincent Siveton
+ ------
+ 2009-08-04
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Using Alternative Output Directory
+
+ To run the Javadocs reports in an other output directory, you need to configure Javadoc Plugin as follow:
+
++-----+
+<project>
+  ...
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          <reportOutputDirectory>\${project.reporting.outputDirectory}/myoutput</reportOutputDirectory>
+          <destDir>myapidocs</destDir>
+          ...
+        </configuration>
+      </plugin>
+      ...
+    </plugins>
+  </reporting>
+  ...
+</project>
++-----+
+
+  Running <<<mvn javadoc:javadoc>>> will output the Javadoc in the
+  <$\{project.reporting.outputDirectory\}/myoutput/myapidocs> instead of the default directory, i.e.
+  <$\{project.reporting.outputDirectory\}/apidocs>.
+
+ <<Note>>: Running <mvn site> will automatically use the <$\{project.reporting.outputDirectory\}> directory and
+ in this case, <reportOutputDirectory> has no effect. Only <destDir> could be used.

src/test/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojoTest.java

@@ -74,6 +74,7 @@ void testMJAVADOC527DetectLinksRecursion() {
         when(log.isErrorEnabled()).thenReturn(true);
         mojo.setLog(log);
         mojo.outputDirectory = new File("target/test-classes");
+        mojo.destDir = "apidocs";
 
         assertThat(mojo.isValidJavadocLink("http://javamail.java.net/mailapi/apidocs", false))
                 .isFalse();

src/test/java/org/apache/maven/plugins/javadoc/JavadocJarMojoTest.java

@@ -132,6 +132,24 @@ void testDefaultConfig(JavadocJarMojo mojo) throws Exception {
         assertThat(generatedFile).exists();
     }
 
+    /**
+     * Test when the specified destDir parameter has an invalid value
+     *
+     * @throws Exception if any
+     */
+    @Test
+    @InjectMojo(goal = "jar", pom = "javadocjar-invalid-destdir-plugin-config.xml")
+    @Basedir("/unit/javadocjar-invalid-destdir")
+    void testInvalidDestdir(JavadocJarMojo mojo) throws Exception {
+        mojo.execute();
+
+        // check if the javadoc jar file was generated
+        File generatedFile = new File(
+                getBasedir(),
+                "target/test/unit/javadocjar-invalid-destdir/target/javadocjar-invalid-destdir-javadoc.jar");
+        assertThat(generatedFile).doesNotExist();
+    }
+
     @Test
     @InjectMojo(goal = "jar", pom = "javadocjar-failonerror-plugin-config.xml")
     @Basedir("/unit/javadocjar-failonerror")

src/test/java/org/apache/maven/plugins/javadoc/JavadocReportTest.java

@@ -357,7 +357,7 @@ void testDocfilesWithJava(JavadocReport mojo) throws Exception {
     void testCustomConfiguration(JavadocReport mojo) throws Exception {
         mojo.execute();
 
-        Path apidocs = new File(getBasedir(), "/target/site/apidocs").toPath();
+        Path apidocs = new File(getBasedir(), "/target/site/myapidocs").toPath();
 
         // check if there is a tree page generated (notree == true)
         assertThat(apidocs.resolve("overview-tree.html")).doesNotExist();

src/test/resources/unit/custom-configuration/custom-configuration-plugin-config.xml

@@ -35,6 +35,7 @@ under the License.
         <configuration>
           <sourcepath>${basedir}</sourcepath>
           <outputDirectory>${basedir}/target/site</outputDirectory>
+          <destDir>myapidocs</destDir>
           <javadocOptionsDir>${basedir}/target/javadoc-bundle-options</javadocOptionsDir>
           <breakiterator>false</breakiterator>
           <old>true</old>

src/test/resources/unit/javadocjar-invalid-destdir/javadocjar-invalid-destdir-plugin-config.xml

@@ -0,0 +1,73 @@
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>org.apache.maven.plugins.maven-javadoc-plugin.unit</groupId>
+  <artifactId>javadocjar-invalid-destdir</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <inceptionYear>2006</inceptionYear>
+  <name>Maven Javadoc Plugin Javadoc Jar Invalid Destdir Test</name>
+  <url>http://maven.apache.org</url>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <destDir>${basedir}/target/test/unit/javadocjar-invalid-destdir/target/invalid</destDir>
+          <jarOutputDirectory>${basedir}/target/test/unit/javadocjar-invalid-destdir/target</jarOutputDirectory>
+          <outputDirectory>${basedir}/target/test/unit/javadocjar-invalid-destdir/target/site/apidocs</outputDirectory>
+          <javadocOptionsDir>${basedir}/target/test/unit/javadocjar-invalid-destdir/target/javadoc-bundle-options</javadocOptionsDir>
+          <finalName>javadocjar-invalid-destdir</finalName>
+          <attach>true</attach>
+          <breakiterator>false</breakiterator>
+          <old>false</old>
+          <show>protected</show>
+          <quiet>true</quiet>
+          <verbose>false</verbose>
+          <author>true</author>
+          <encoding>ISO-8859-1</encoding>
+          <docfilessubdirs>false</docfilessubdirs>
+          <linksource>false</linksource>
+          <nocomment>false</nocomment>
+          <nodeprecated>false</nodeprecated>
+          <nodeprecatedlist>false</nodeprecatedlist>
+          <nohelp>false</nohelp>
+          <noindex>false</noindex>
+          <nonavbar>false</nonavbar>
+          <nosince>false</nosince>
+          <notree>false</notree>
+          <serialwarn>false</serialwarn>
+          <splitindex>false</splitindex>
+          <stylesheet>java</stylesheet>
+          <groups/>
+          <tags/>
+          <use>true</use>
+          <version>true</version>
+          <windowtitle>Maven Javadoc Plugin Javadoc Jar Invalid Destdir Test 1.0-SNAPSHOT API</windowtitle>
+          <debug>true</debug>
+          <failOnError>true</failOnError>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/App.java

@@ -0,0 +1,50 @@
+package javadocjar.invalid.destdir;
+
+/*
+ * 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.
+ */
+
+/**
+ * This is a sample app class with javadoc
+ *
+ * @author Maria Odea Ching
+ */
+public class App
+{
+
+    /**
+     * The main method
+     *
+     * @param args  an array of strings that contains the arguments
+     */
+    public static void main( String[] args )
+    {
+        System.out.println( "Sample Application." );
+    }
+
+    /**
+     * Sample method
+     *
+     * @param str   the string to be displayed
+     */
+    protected void sampleMethod( String str )
+    {
+        System.out.println( str );
+    }
+
+}