diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index d542d7d07..bbeb2e637 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/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.: ${project.url}/apidocs. + * Detect the Javadoc links for all dependencies defined in the project. The detection is based + * on the default Maven conventions, i.e.: ${project.url}/${destDir} with + * {@code destDir} from the Javadoc plugin configuration (apidocs by default). *
* For instance, if the project has a dependency to * Apache Commons Lang i.e.: @@ -496,8 +497,10 @@ public AbstractJavadocMojo( * Detect the links for all modules defined in the project. *
* 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 - * module1 and module2, the -linkoffline will be: + * between modules based on the defined project's URLs and {@code destDir} + * in the Javadoc plugin configuration (apidocs by default). + * For instance, if a parent project has two projects + * module1 and module2, the -linkoffline will be by default: *
* The added Javadoc -linkoffline parameter for module1 will be * /absolute/path/to/module2/target/site/apidocs @@ -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 ${project.url}/apidocs. + * Using Maven, a Javadoc link is given by ${project.url}/${destDir} with + * {@code destDir} from the Javadoc plugin configuration (apidocs 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 getModulesLinks() throws MavenReportException { } /** - * Using Maven, a Javadoc link is given by ${project.url}/apidocs. + * Using Maven, a Javadoc link is given by ${project.url}/${destDir} with + * {@code destDir} from the Javadoc plugin configuration (apidocs 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. ${project.url}/apidocs. + * @return the javadoc link based on the project URL i.e. ${project.url}/${destDir} + * with {@code destDir} from the Javadoc plugin configuration (apidocs 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; } /** diff --git a/src/main/java/org/apache/maven/plugins/javadoc/JavadocReport.java b/src/main/java/org/apache/maven/plugins/javadoc/JavadocReport.java index 0b18ac5a1..860d275ec 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/JavadocReport.java +++ b/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} */ diff --git a/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocReport.java b/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocReport.java index 481f1be4b..338389477 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocReport.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocReport.java @@ -263,16 +263,16 @@ private ResourceBundle getBundle(Locale locale) { } /** - * Add the ../apidocs to the links parameter so Test report could be linked to the Main report. + * Add the ../${destDir} 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); } } diff --git a/src/site/apt/examples/output-configuration.apt.vm b/src/site/apt/examples/output-configuration.apt.vm new file mode 100644 index 000000000..e9800a4fc --- /dev/null +++ b/src/site/apt/examples/output-configuration.apt.vm @@ -0,0 +1,59 @@ + ------ + 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 another output directory, you need to configure Javadoc Plugin as follows: ++-----+ + + ... + + + + org.apache.maven.plugins + maven-javadoc-plugin + ${project.version} + + \${project.reporting.outputDirectory}/myoutput + myapidocs + ... + + + ... + + + ... + ++-----+ + + Running <<>> will output the Javadoc in the + <$\{project.reporting.outputDirectory\}/myoutput/myapidocs> instead of the default directory, i.e. + <$\{project.reporting.outputDirectory\}/apidocs>. + + <>: Running will automatically use the <$\{project.reporting.outputDirectory\}> directory and + in this case, has no effect. Only could be used. diff --git a/src/test/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojoTest.java b/src/test/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojoTest.java index 9a9fc6c4b..be7815bc7 100644 --- a/src/test/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojoTest.java +++ b/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(); diff --git a/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarMojoTest.java b/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarMojoTest.java index f36257eb0..aba340f99 100644 --- a/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarMojoTest.java +++ b/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") diff --git a/src/test/java/org/apache/maven/plugins/javadoc/JavadocReportTest.java b/src/test/java/org/apache/maven/plugins/javadoc/JavadocReportTest.java index d6c510f18..2f6cd49f8 100644 --- a/src/test/java/org/apache/maven/plugins/javadoc/JavadocReportTest.java +++ b/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(); diff --git a/src/test/resources/unit/custom-configuration/custom-configuration-plugin-config.xml b/src/test/resources/unit/custom-configuration/custom-configuration-plugin-config.xml index b2296f550..91fa6a229 100644 --- a/src/test/resources/unit/custom-configuration/custom-configuration-plugin-config.xml +++ b/src/test/resources/unit/custom-configuration/custom-configuration-plugin-config.xml @@ -35,6 +35,7 @@ under the License. ${basedir} ${basedir}/target/site + myapidocs ${basedir}/target/javadoc-bundle-options false true diff --git a/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar-invalid-destdir-plugin-config.xml b/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar-invalid-destdir-plugin-config.xml new file mode 100644 index 000000000..819a9db4c --- /dev/null +++ b/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar-invalid-destdir-plugin-config.xml @@ -0,0 +1,73 @@ + + + + 4.0.0 + org.apache.maven.plugins.maven-javadoc-plugin.unit + javadocjar-invalid-destdir + jar + 1.0-SNAPSHOT + 2006 + Maven Javadoc Plugin Javadoc Jar Invalid Destdir Test + http://maven.apache.org + + + + org.apache.maven.plugins + maven-javadoc-plugin + + ${basedir}/target/test/unit/javadocjar-invalid-destdir/target/invalid + ${basedir}/target/test/unit/javadocjar-invalid-destdir/target + ${basedir}/target/test/unit/javadocjar-invalid-destdir/target/site/apidocs + ${basedir}/target/test/unit/javadocjar-invalid-destdir/target/javadoc-bundle-options + javadocjar-invalid-destdir + true + false + false + protected + true + false + true + ISO-8859-1 + false + false + false + false + false + false + false + false + false + false + false + false + java + + + true + true + Maven Javadoc Plugin Javadoc Jar Invalid Destdir Test 1.0-SNAPSHOT API + true + true + + + + + diff --git a/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/App.java b/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/App.java new file mode 100644 index 000000000..ea377917c --- /dev/null +++ b/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 ); + } + +} diff --git a/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/AppSample.java b/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/AppSample.java new file mode 100644 index 000000000..801c36d46 --- /dev/null +++ b/src/test/resources/unit/javadocjar-invalid-destdir/javadocjar/invalid/destdir/AppSample.java @@ -0,0 +1,45 @@ +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 class with javadoc + * + * @author Maria Odea Ching + */ +public class AppSample +{ + + /** + * Variable that holds the test value + */ + private String str = "TEST"; + + /** + * The main method + * + * @param args an array of strings that contains the arguments + */ + public static void main( String[] args ) + { + System.out.println( "Another Sample Application" ); + } + +}