Skip to content

Commit 339fc29

Browse files
kwinkwin
authored
[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
1 parent a191579 commit 339fc29

File tree

12 files changed

+448
-19
lines changed

12 files changed

+448
-19
lines changed

‎maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/report_old/PluginReport.java

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,19 @@ public class PluginReport
218218
readonly = true )
219219
private File enhancedPluginXmlFile;
220220

221+
/**
222+
* In case the internal javadoc site has not been generated when running this report goal
223+
* (e.g. when using an aggregator javadoc report) link validation needs to be disabled by setting
224+
* this value to {@code true}.
225+
* This might have the drawback that some links being generated in the report might be broken
226+
* in case not all parameter types and javadoc link references are resolvable through the sites being given to
227+
* {@link DescriptorGeneratorMojo}.
228+
*
229+
* @since 3.7.0
230+
*/
231+
@Parameter( property = "maven.plugin.report.disableInternalJavadocLinkValidation" )
232+
private boolean disableInternalJavadocLinkValidation;
233+
221234
/**
222235
* {@inheritDoc}
223236
*/
@@ -324,7 +337,8 @@ private void generateMojosDocumentation( PluginDescriptor pluginDescriptor, Loca
324337
File outputDir = outputDirectory;
325338
outputDir.mkdirs();
326339

327-
PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory() );
340+
PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory(),
341+
disableInternalJavadocLinkValidation );
328342
PluginToolsRequest pluginToolsRequest = new DefaultPluginToolsRequest( getProject(), pluginDescriptor );
329343
generator.execute( outputDir, pluginToolsRequest );
330344
}

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/invoker.properties

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
invoker.goals = clean site -Dmaven.plugin.report.disableInternalJavadocLinkValidation=true

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/pom.xml

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
3+
<!--
4+
Licensed to the Apache Software Foundation (ASF) under one
5+
or more contributor license agreements. See the NOTICE file
6+
distributed with this work for additional information
7+
regarding copyright ownership. The ASF licenses this file
8+
to you under the Apache License, Version 2.0 (the
9+
"License"); you may not use this file except in compliance
10+
with the License. You may obtain a copy of the License at
11+
12+
http://www.apache.org/licenses/LICENSE-2.0
13+
14+
Unless required by applicable law or agreed to in writing,
15+
software distributed under the License is distributed on an
16+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17+
KIND, either express or implied. See the License for the
18+
specific language governing permissions and limitations
19+
under the License.
20+
-->
21+
22+
<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">
23+
<modelVersion>4.0.0</modelVersion>
24+
25+
<groupId>org.apache.maven.its</groupId>
26+
<artifactId>plugin-report</artifactId>
27+
<version>1.0-SNAPSHOT</version>
28+
<packaging>maven-plugin</packaging>
29+
30+
<name>MPLUGIN-417</name>
31+
<description>
32+
Test basic site generation containing javadoc links to internal and external javadoc sites.
33+
</description>
34+
<properties>
35+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
36+
</properties>
37+
38+
<dependencies>
39+
<dependency>
40+
<groupId>org.apache.maven</groupId>
41+
<artifactId>maven-plugin-api</artifactId>
42+
<version>@mavenVersion@</version>
43+
<scope>provided</scope>
44+
</dependency>
45+
<dependency>
46+
<groupId>org.apache.maven.plugin-tools</groupId>
47+
<artifactId>maven-plugin-annotations</artifactId>
48+
<version>@project.version@</version>
49+
<scope>provided</scope>
50+
</dependency>
51+
<dependency>
52+
<groupId>org.apache.maven</groupId>
53+
<artifactId>maven-artifact</artifactId>
54+
<version>@mavenVersion@</version>
55+
<scope>provided</scope>
56+
</dependency>
57+
<dependency>
58+
<groupId>org.apache.maven</groupId>
59+
<artifactId>maven-core</artifactId>
60+
<version>@mavenVersion@</version>
61+
<scope>provided</scope>
62+
</dependency>
63+
<dependency>
64+
<groupId>org.apache.maven.reporting</groupId>
65+
<artifactId>maven-reporting-api</artifactId>
66+
<version>@reportingApiVersion@</version>
67+
</dependency>
68+
<dependency>
69+
<groupId>org.apache.maven.reporting</groupId>
70+
<artifactId>maven-reporting-impl</artifactId>
71+
<version>@reportingImplVersion@</version>
72+
</dependency>
73+
74+
</dependencies>
75+
76+
<build>
77+
<plugins>
78+
<plugin>
79+
<groupId>org.apache.maven.plugins</groupId>
80+
<artifactId>maven-compiler-plugin</artifactId>
81+
<version>3.5.1</version>
82+
<configuration>
83+
<!-- old maven-parent, so fix it like this. -->
84+
<source>${maven.compiler.source}</source>
85+
<target>${maven.compiler.target}</target>
86+
</configuration>
87+
</plugin>
88+
<plugin>
89+
<groupId>org.apache.maven.plugins</groupId>
90+
<artifactId>maven-plugin-plugin</artifactId>
91+
<version>@project.version@</version>
92+
<configuration>
93+
<internalJavadocBaseUrl>./apidocs/</internalJavadocBaseUrl>
94+
<externalJavadocBaseUrls>
95+
<externalJavadocBaseUrl>https://docs.oracle.com/javase/8/docs/api/</externalJavadocBaseUrl>
96+
</externalJavadocBaseUrls>
97+
</configuration>
98+
</plugin>
99+
<plugin>
100+
<groupId>org.apache.maven.plugins</groupId>
101+
<artifactId>maven-site-plugin</artifactId>
102+
<version>@sitePluginVersion@</version>
103+
<configuration>
104+
<locales>en</locales>
105+
</configuration>
106+
</plugin>
107+
</plugins>
108+
</build>
109+
110+
<reporting>
111+
<plugins>
112+
<plugin>
113+
<groupId>org.apache.maven.plugins</groupId>
114+
<artifactId>maven-project-info-reports-plugin</artifactId>
115+
<version>@projectInfoReportsPlugin@</version>
116+
<reportSets>
117+
<reportSet>
118+
<reports>
119+
<report>index</report>
120+
</reports>
121+
</reportSet>
122+
</reportSets>
123+
</plugin>
124+
<plugin>
125+
<groupId>org.apache.maven.plugins</groupId>
126+
<artifactId>maven-javadoc-plugin</artifactId>
127+
<version>3.4.1</version>
128+
<configuration>
129+
<excludePackageNames>org.internal</excludePackageNames>
130+
</configuration>
131+
<reportSets>
132+
<reportSet>
133+
<reports>
134+
<report>javadoc</report>
135+
</reports>
136+
</reportSet>
137+
</reportSets>
138+
</plugin>
139+
<plugin>
140+
<groupId>org.apache.maven.plugins</groupId>
141+
<artifactId>maven-plugin-report-plugin</artifactId>
142+
<version>@project.version@</version>
143+
</plugin>
144+
</plugins>
145+
</reporting>
146+
</project>

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/MyMojo.java

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
package org;
2+
3+
/*
4+
* Licensed to the Apache Software Foundation (ASF) under one
5+
* or more contributor license agreements. See the NOTICE file
6+
* distributed with this work for additional information
7+
* regarding copyright ownership. The ASF licenses this file
8+
* to you under the Apache License, Version 2.0 (the
9+
* "License"); you may not use this file except in compliance
10+
* with the License. You may obtain a copy of the License at
11+
*
12+
* http://www.apache.org/licenses/LICENSE-2.0
13+
*
14+
* Unless required by applicable law or agreed to in writing,
15+
* software distributed under the License is distributed on an
16+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17+
* KIND, either express or implied. See the License for the
18+
* specific language governing permissions and limitations
19+
* under the License.
20+
*/
21+
22+
import java.util.Collection;
23+
import java.util.Map;
24+
25+
import org.apache.maven.plugin.AbstractMojo;
26+
import org.apache.maven.plugins.annotations.Mojo;
27+
import org.apache.maven.plugins.annotations.Parameter;
28+
29+
/**
30+
* Some description
31+
*
32+
* @see java.util.Collections
33+
*
34+
*/
35+
@Mojo( name = "test" )
36+
public class MyMojo
37+
extends AbstractMojo
38+
{
39+
40+
/**
41+
* beans parameter leveraging {@link SimpleBean}.
42+
*/
43+
@Parameter
44+
public Collection<SimpleBean> beans;
45+
46+
/**
47+
* invalid javadoc reference {@link org.apache.maven.artifact.Artifact}.
48+
*/
49+
@Parameter
50+
public Map<String,Boolean> invalidReference;
51+
52+
@Parameter
53+
org.internal.PrivateBean privateBean;
54+
55+
public void execute()
56+
{
57+
// intentional do nothing
58+
}
59+
60+
}

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/SimpleBean.java

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
package org;
2+
3+
/*
4+
* Licensed to the Apache Software Foundation (ASF) under one
5+
* or more contributor license agreements. See the NOTICE file
6+
* distributed with this work for additional information
7+
* regarding copyright ownership. The ASF licenses this file
8+
* to you under the Apache License, Version 2.0 (the
9+
* "License"); you may not use this file except in compliance
10+
* with the License. You may obtain a copy of the License at
11+
*
12+
* http://www.apache.org/licenses/LICENSE-2.0
13+
*
14+
* Unless required by applicable law or agreed to in writing,
15+
* software distributed under the License is distributed on an
16+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17+
* KIND, either express or implied. See the License for the
18+
* specific language governing permissions and limitations
19+
* under the License.
20+
*/
21+
22+
/**
23+
* Some simple bean used in parameters of {@link MyMojo}.
24+
*/
25+
public class SimpleBean
26+
{
27+
public Integer field1;
28+
}

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/src/main/java/org/internal/PrivateBean.java

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
package org.internal;
2+
3+
/*
4+
* Licensed to the Apache Software Foundation (ASF) under one
5+
* or more contributor license agreements. See the NOTICE file
6+
* distributed with this work for additional information
7+
* regarding copyright ownership. The ASF licenses this file
8+
* to you under the Apache License, Version 2.0 (the
9+
* "License"); you may not use this file except in compliance
10+
* with the License. You may obtain a copy of the License at
11+
*
12+
* http://www.apache.org/licenses/LICENSE-2.0
13+
*
14+
* Unless required by applicable law or agreed to in writing,
15+
* software distributed under the License is distributed on an
16+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17+
* KIND, either express or implied. See the License for the
18+
* specific language governing permissions and limitations
19+
* under the License.
20+
*/
21+
22+
/**
23+
* Bean which does not have javadoc
24+
*/
25+
public class PrivateBean
26+
{
27+
public Integer field1;
28+
}

‎maven-plugin-report-plugin/src/it/plugin-report-with-javadoc-links/verify.groovy

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
def mojoDoc = new File( basedir, 'target/site/test-mojo.html' )
21+
22+
assert mojoDoc.isFile()
23+
24+
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
25+
26+
assert mojoDoc.text.contains('beans parameter leveraging <a href="apidocs/org/SimpleBean.html"><code>SimpleBean</code></a>.') // parameter description
27+
assert mojoDoc.text.contains('<td><code><a href="apidocs/org/SimpleBean.html">Collection&lt;SimpleBean&gt;</a></code></td>') // type link in parameter overview
28+
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
29+
30+
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)
31+
32+
// the third parameter contains an invalid link (as the internal link validation has been switched off)
33+
assert mojoDoc.text.contains(' <code><a href="apidocs/org/internal/PrivateBean.html">org.internal.PrivateBean</a></code>')

‎maven-plugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/PluginReport.java

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,19 @@ public class PluginReport
130130
readonly = true )
131131
private File enhancedPluginXmlFile;
132132

133+
/**
134+
* In case the internal javadoc site has not been generated when running this report goal
135+
* (e.g. when using an aggregator javadoc report) link validation needs to be disabled by setting
136+
* this value to {@code true}.
137+
* This might have the drawback that some links being generated in the report might be broken
138+
* in case not all parameter types and javadoc link references are resolvable through the sites being given to
139+
* goal {@code plugin:descriptor}.
140+
*
141+
* @since 3.7.0
142+
*/
143+
@Parameter( property = "maven.plugin.report.disableInternalJavadocLinkValidation" )
144+
private boolean disableInternalJavadocLinkValidation;
145+
133146
/**
134147
* {@inheritDoc}
135148
*/
@@ -232,7 +245,8 @@ private void generateMojosDocumentation( PluginDescriptor pluginDescriptor, Loca
232245
File outputDir = outputDirectory;
233246
outputDir.mkdirs();
234247

235-
PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory() );
248+
PluginXdocGenerator generator = new PluginXdocGenerator( getProject(), locale, getReportOutputDirectory(),
249+
disableInternalJavadocLinkValidation );
236250
PluginToolsRequest pluginToolsRequest = new DefaultPluginToolsRequest( getProject(), pluginDescriptor );
237251
generator.execute( outputDir, pluginToolsRequest );
238252
}

‎maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,13 @@ public static boolean isLinkValid( URI url, Path baseDirectory )
253253
}
254254
else
255255
{
256-
return Files.exists( baseDirectory.resolve( url.getPath() ) );
256+
Path file = baseDirectory.resolve( url.getPath() );
257+
boolean exists = Files.exists( file );
258+
if ( !exists )
259+
{
260+
LOG.debug( "Could not find file given through '{}' in resolved path '{}'", url, file );
261+
}
262+
return exists;
257263
}
258264
}
259265
}

0 commit comments

Comments
 (0)