Skip to content

Commit 3d26e03

Browse files
marko-bekhtamarko-bekhta
committed
Add the "addScripts" configuration parameter
to support the "--add-script" argument of the javadoc tool: https://docs.oracle.com/en/java/javase/18/docs/specs/man/javadoc.html
1 parent ee7590f commit 3d26e03

File tree

8 files changed

+240
-0
lines changed

8 files changed

+240
-0
lines changed

‎src/it/projects/addscript/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=compile javadoc:javadoc

‎src/it/projects/addscript/pom.xml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
3+
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor
4+
license agreements. See the NOTICE file distributed with this work for additional
5+
information regarding copyright ownership. The ASF licenses this file to
6+
you under the Apache License, Version 2.0 (the "License"); you may not use
7+
this file except in compliance with the License. You may obtain a copy of
8+
the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required
9+
by applicable law or agreed to in writing, software distributed under the
10+
License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
11+
OF ANY KIND, either express or implied. See the License for the specific
12+
language governing permissions and limitations under the License. -->
13+
14+
<project xmlns="http://maven.apache.org/POM/4.0.0"
15+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
16+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
17+
<modelVersion>4.0.0</modelVersion>
18+
<groupId>org.apache.maven.plugins.javadoc.it</groupId>
19+
<artifactId>addscript</artifactId>
20+
<version>1.0.0-SNAPSHOT</version>
21+
22+
<properties>
23+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
24+
<maven.compiler.source>@maven.compiler.source@</maven.compiler.source>
25+
<maven.compiler.target>@maven.compiler.target@</maven.compiler.target>
26+
</properties>
27+
28+
<build>
29+
<plugins>
30+
<plugin>
31+
<groupId>org.apache.maven.plugins</groupId>
32+
<artifactId>maven-compiler-plugin</artifactId>
33+
<version>@compilerPluginVersion@</version>
34+
</plugin>
35+
<plugin>
36+
<groupId>org.apache.maven.plugins</groupId>
37+
<artifactId>maven-javadoc-plugin</artifactId>
38+
<version>@project.version@</version>
39+
<configuration>
40+
<addScripts>
41+
<addScript>resources/custom-script.js</addScript>
42+
<addScript>resources/custom-script1.js</addScript>
43+
<addScript>resources/custom-script2.js</addScript>
44+
</addScripts>
45+
</configuration>
46+
</plugin>
47+
</plugins>
48+
</build>
49+
50+
</project>

‎src/it/projects/addscript/src/main/java/com/example/AddScriptJavaDoc.java‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
package com.example;
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+
* Support for multiple extra scripts
24+
*/
25+
public class AddScriptJavaDoc
26+
{
27+
28+
}

‎src/it/projects/addscript/src/main/javadoc/resources/custom-script.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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+
console.log('script');

‎src/it/projects/addscript/src/main/javadoc/resources/custom-script1.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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+
console.log('script1');

‎src/it/projects/addscript/src/main/javadoc/resources/custom-script2.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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+
console.log('script2');

‎src/it/projects/addscript/verify.groovy‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
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 file = new File( basedir, 'target/reports/apidocs/com/example/AddScriptJavaDoc.html' );
21+
22+
assert file.exists()
23+
24+
def javaVersion = System.getProperty( 'java.specification.version' )
25+
if( javaVersion ==~ /(1\..+|9\..+|1[0-7]\..+)/ )
26+
{
27+
assert new File(basedir, 'build.log').text.contains('--add-scripts option is not supported on Java version < 18')
28+
}
29+
else
30+
{
31+
assert 1 == file.text.count('custom-script.js')
32+
assert 1 == file.text.count('custom-script1.js')
33+
assert 1 == file.text.count('custom-script2.js')
34+
}

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1310,6 +1310,22 @@ public AbstractJavadocMojo(
13101310
@Parameter
13111311
private String[] addStylesheets;
13121312

1313+
/**
1314+
* Specifies the path of an additional script file relative to the {@code javadocDirectory}
1315+
* Example:
1316+
* <pre>
1317+
* &lt;addScripts&gt;
1318+
* &lt;addScript&gt;resources/script.js&lt;/addScript&gt;
1319+
* &lt;/addScripts&gt;
1320+
* </pre>
1321+
* <p>
1322+
* These script files are passed to the Javadoc tool via the {@code --add-script} parameter.
1323+
* This option is available since JDK 18.
1324+
* @since 3.13.0
1325+
*/
1326+
@Parameter
1327+
private String[] addScripts;
1328+
13131329
/**
13141330
* Specifies the class file that starts the taglet used in generating the documentation for that tag.
13151331
* @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option taglet</a>.
@@ -2789,6 +2805,38 @@ private Optional<File> getAddStylesheet(final File javadocOutputDirectory, final
27892805
"additional stylesheet file does not exist: " + addstylesheetfile.getAbsolutePath());
27902806
}
27912807

2808+
private void addAddScripts(List<String> arguments) throws MavenReportException {
2809+
if (addScripts == null) {
2810+
return;
2811+
}
2812+
2813+
for (String addScript : addScripts) {
2814+
Optional<File> script = getAddScript(getJavadocDirectory(), addScript);
2815+
2816+
if (script.isPresent()) {
2817+
addArgIfNotEmpty(
2818+
arguments,
2819+
"--add-script",
2820+
JavadocUtil.quotedPathArgument(script.get().getAbsolutePath()),
2821+
JavaVersion.parse("18"));
2822+
}
2823+
}
2824+
}
2825+
2826+
private Optional<File> getAddScript(final File javadocOutputDirectory, final String script)
2827+
throws MavenReportException {
2828+
if (script == null || script.isEmpty()) {
2829+
return Optional.empty();
2830+
}
2831+
2832+
File scriptFile = new File(getJavadocDirectory(), script);
2833+
if (scriptFile.exists()) {
2834+
return Optional.of(scriptFile);
2835+
}
2836+
2837+
throw new MavenReportException("script file does not exist: " + scriptFile.getAbsolutePath());
2838+
}
2839+
27922840
/**
27932841
* Method to get the help file to be used by the Javadoc Tool.
27942842
* <br/>
@@ -4761,6 +4809,8 @@ private void addStandardDocletOptions(
47614809

47624810
addAddStyleSheets(arguments);
47634811

4812+
addAddScripts(arguments);
4813+
47644814
addArgIfNotEmpty(arguments, "-subpackages", subpackages);
47654815

47664816
addArgIfNotEmpty(arguments, "-taglet", JavadocUtil.quotedArgument(taglet));

0 commit comments

Comments
 (0)