[MPLUGIN-433] Allow to disable link validation (#162)

Also validate internal links to javadocs in mojo/parameter description and deprecated info Add IT for checking javadoc links
apache · Oct 27, 2022 · 339fc29 · 339fc29
1 parent a191579
commit 339fc29
Show file tree

Hide file tree

Showing 12 changed files with 448 additions and 19 deletions.
diff --git a/...n-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/report_old/PluginReport.java b/...n-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/report_old/PluginReport.java
@@ -218,6 +218,19 @@ public class PluginReport
                 readonly = true )
     private File enhancedPluginXmlFile;
 
+    /**
+     * In case the internal javadoc site has not been generated when running this report goal
+     * (e.g. when using an aggregator javadoc report) link validation needs to be disabled by setting
+     * this value to {@code true}.
+     * This might have the drawback that some links being generated in the report might be broken
+     * in case not all parameter types and javadoc link references are resolvable through the sites being given to
+     * {@link DescriptorGeneratorMojo}.
+     * 
+     * @since 3.7.0
+     */
+    @Parameter( property = "maven.plugin.report.disableInternalJavadocLinkValidation" )
+    private boolean disableInternalJavadocLinkValidation;
+
     /**
      * {@inheritDoc}
      */
@@ -324,7 +337,8 @@ private void generateMojosDocumentation( PluginDescriptor pluginDescriptor, Loca
             File outputDir = outputDirectory;
             outputDir.mkdirs();
 
-            PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory() );
+            PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory(),
+                                                                     disableInternalJavadocLinkValidation );
             PluginToolsRequest pluginToolsRequest = new DefaultPluginToolsRequest( getProject(), pluginDescriptor );
             generator.execute( outputDir, pluginToolsRequest );
         }

diff --git a/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/invoker.properties b/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/invoker.properties
@@ -0,0 +1,18 @@
+# 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.
+
+invoker.goals = clean site -Dmaven.plugin.report.disableInternalJavadocLinkValidation=true
diff --git a/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/pom.xml b/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/pom.xml
@@ -0,0 +1,146 @@
+<?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.
+-->
+
+<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.its</groupId>
+  <artifactId>plugin-report</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>maven-plugin</packaging>
+
+  <name>MPLUGIN-417</name> 
+  <description>
+    Test basic site generation containing javadoc links to internal and external javadoc sites.
+  </description>
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-plugin-api</artifactId>
+      <version>@mavenVersion@</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven.plugin-tools</groupId>
+      <artifactId>maven-plugin-annotations</artifactId>
+      <version>@project.version@</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-artifact</artifactId>
+      <version>@mavenVersion@</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-core</artifactId>
+      <version>@mavenVersion@</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven.reporting</groupId>
+      <artifactId>maven-reporting-api</artifactId>
+      <version>@reportingApiVersion@</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven.reporting</groupId>
+      <artifactId>maven-reporting-impl</artifactId>
+      <version>@reportingImplVersion@</version>
+    </dependency>
+
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.5.1</version>
+        <configuration>
+          <!-- old maven-parent, so fix it like this. -->
+          <source>${maven.compiler.source}</source>
+          <target>${maven.compiler.target}</target>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-plugin-plugin</artifactId>
+        <version>@project.version@</version>
+        <configuration>
+          <internalJavadocBaseUrl>./apidocs/</internalJavadocBaseUrl>
+          <externalJavadocBaseUrls>
+            <externalJavadocBaseUrl>https://docs.oracle.com/javase/8/docs/api/</externalJavadocBaseUrl>
+          </externalJavadocBaseUrls>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-site-plugin</artifactId>
+        <version>@sitePluginVersion@</version>
+        <configuration>
+          <locales>en</locales>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-project-info-reports-plugin</artifactId>
+        <version>@projectInfoReportsPlugin@</version>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>index</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>3.4.1</version>
+        <configuration>
+          <excludePackageNames>org.internal</excludePackageNames>
+        </configuration>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>javadoc</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-plugin-report-plugin</artifactId>
+        <version>@project.version@</version>
+      </plugin>
+    </plugins>
+  </reporting>
+</project>
diff --git a/...lugin-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/MyMojo.java b/...lugin-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/MyMojo.java
@@ -0,0 +1,60 @@
+package org;
+
+/*
+ * 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.
+ */
+
+import java.util.Collection;
+import java.util.Map;
+
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugins.annotations.Mojo;
+import org.apache.maven.plugins.annotations.Parameter;
+
+/**
+ * Some description
+ * 
+ * @see java.util.Collections
+ *
+ */
+@Mojo( name = "test" )
+public class MyMojo
+    extends AbstractMojo
+{
+
+    /**
+     * beans parameter leveraging {@link SimpleBean}.
+     */
+    @Parameter
+    public Collection<SimpleBean> beans;
+
+    /**
+     * invalid javadoc reference {@link org.apache.maven.artifact.Artifact}.
+     */
+    @Parameter
+    public Map<String,Boolean> invalidReference;
+
+    @Parameter
+    org.internal.PrivateBean privateBean;
+
+    public void execute()
+    {
+        // intentional do nothing
+    }
+
+}
diff --git a/...n-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/SimpleBean.java b/...n-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/SimpleBean.java
@@ -0,0 +1,28 @@
+package org;
+
+/*
+ * 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.
+ */
+
+/**
+ * Some simple bean used in parameters of {@link MyMojo}.
+ */
+public class SimpleBean
+{
+    public Integer field1;
+}
diff --git a/...lugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/internal/PrivateBean.java b/...lugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/internal/PrivateBean.java
@@ -0,0 +1,28 @@
+package org.internal;
+
+/*
+ * 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.
+ */
+
+/**
+ * Bean which does not have javadoc
+ */
+public class PrivateBean
+{
+    public Integer field1;
+}
diff --git a/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/verify.groovy b/maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/verify.groovy
@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+def mojoDoc = new File( basedir, 'target/site/test-mojo.html' )
+
+assert mojoDoc.isFile()
+
+assert mojoDoc.text.contains('<b>See also:</b> <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/util/Collections.html">java.util.Collections</a></div>') // mojo description see javadoc tag
+
+assert mojoDoc.text.contains('beans parameter leveraging <a href="apidocs/org/SimpleBean.html"><code>SimpleBean</code></a>.') // parameter description
+assert mojoDoc.text.contains('<td><code><a href="apidocs/org/SimpleBean.html">Collection&lt;SimpleBean&gt;</a></code></td>') // type link in parameter overview
+assert mojoDoc.text.contains('<li><b>Type</b>: <code><a href="apidocs/org/SimpleBean.html">java.util.Collection&lt;org.SimpleBean&gt;</a></code></li>') // type link in parameter details
+
+assert mojoDoc.text.contains('<div>invalid javadoc reference <code>org.apache.maven.artifact.Artifact</code>.</div>') // second parameter description with link being removed (as no javadoc site associated)
+
+// the third parameter contains an invalid link (as the internal link validation has been switched off)
+assert mojoDoc.text.contains(' <code><a href="apidocs/org/internal/PrivateBean.html">org.internal.PrivateBean</a></code>')
diff --git a/...lugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/PluginReport.java b/...lugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/PluginReport.java
@@ -130,6 +130,19 @@ public class PluginReport
                 readonly = true )
     private File enhancedPluginXmlFile;
 
+    /**
+     * In case the internal javadoc site has not been generated when running this report goal
+     * (e.g. when using an aggregator javadoc report) link validation needs to be disabled by setting
+     * this value to {@code true}.
+     * This might have the drawback that some links being generated in the report might be broken
+     * in case not all parameter types and javadoc link references are resolvable through the sites being given to
+     * goal {@code plugin:descriptor}.
+     * 
+     * @since 3.7.0
+     */
+    @Parameter( property = "maven.plugin.report.disableInternalJavadocLinkValidation" )
+    private boolean disableInternalJavadocLinkValidation;
+
     /**
      * {@inheritDoc}
      */
@@ -232,7 +245,8 @@ private void generateMojosDocumentation( PluginDescriptor pluginDescriptor, Loca
             File outputDir = outputDirectory;
             outputDir.mkdirs();
 
-            PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory() );
+            PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory(),
+                                                                     disableInternalJavadocLinkValidation );
             PluginToolsRequest pluginToolsRequest = new DefaultPluginToolsRequest( getProject(), pluginDescriptor );
             generator.execute( outputDir, pluginToolsRequest );
         }

diff --git a/...n-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java b/...n-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java
@@ -253,7 +253,13 @@ public static boolean isLinkValid( URI url, Path baseDirectory )
         }
         else
         {
-            return Files.exists( baseDirectory.resolve( url.getPath() ) );
+            Path file = baseDirectory.resolve( url.getPath() );
+            boolean exists = Files.exists( file );
+            if ( !exists )
+            {
+                LOG.debug( "Could not find file given through '{}' in resolved path '{}'", url, file );
+            }
+            return exists;
         }
     }
 }