From 68c88358a66471ae4abf8589ac9499e8b9a9d0c9 Mon Sep 17 00:00:00 2001 From: marko-bekhta Date: Tue, 28 Oct 2025 12:20:52 +0100 Subject: [PATCH] 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 --- src/it/projects/addscript/invoker.properties | 19 +++++++ src/it/projects/addscript/pom.xml | 50 +++++++++++++++++ .../java/com/example/AddScriptJavaDoc.java | 28 ++++++++++ .../main/javadoc/resources/custom-script.js | 20 +++++++ .../main/javadoc/resources/custom-script1.js | 20 +++++++ .../main/javadoc/resources/custom-script2.js | 20 +++++++ src/it/projects/addscript/verify.groovy | 26 +++++++++ .../plugins/javadoc/AbstractJavadocMojo.java | 56 +++++++++++++++++++ 8 files changed, 239 insertions(+) create mode 100644 src/it/projects/addscript/invoker.properties create mode 100644 src/it/projects/addscript/pom.xml create mode 100644 src/it/projects/addscript/src/main/java/com/example/AddScriptJavaDoc.java create mode 100644 src/it/projects/addscript/src/main/javadoc/resources/custom-script.js create mode 100644 src/it/projects/addscript/src/main/javadoc/resources/custom-script1.js create mode 100644 src/it/projects/addscript/src/main/javadoc/resources/custom-script2.js create mode 100644 src/it/projects/addscript/verify.groovy diff --git a/src/it/projects/addscript/invoker.properties b/src/it/projects/addscript/invoker.properties new file mode 100644 index 000000000..303cfaa57 --- /dev/null +++ b/src/it/projects/addscript/invoker.properties @@ -0,0 +1,19 @@ +# 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=compile javadoc:javadoc +invoker.java.version = 18+ diff --git a/src/it/projects/addscript/pom.xml b/src/it/projects/addscript/pom.xml new file mode 100644 index 000000000..b06e5b6df --- /dev/null +++ b/src/it/projects/addscript/pom.xml @@ -0,0 +1,50 @@ + + + + + + 4.0.0 + org.apache.maven.plugins.javadoc.it + addscript + 1.0.0-SNAPSHOT + + + UTF-8 + @maven.compiler.source@ + @maven.compiler.target@ + + + + + + org.apache.maven.plugins + maven-compiler-plugin + @compilerPluginVersion@ + + + org.apache.maven.plugins + maven-javadoc-plugin + @project.version@ + + + resources/custom-script.js + resources/custom-script1.js + resources/custom-script2.js + + + + + + + diff --git a/src/it/projects/addscript/src/main/java/com/example/AddScriptJavaDoc.java b/src/it/projects/addscript/src/main/java/com/example/AddScriptJavaDoc.java new file mode 100644 index 000000000..1f5956cd5 --- /dev/null +++ b/src/it/projects/addscript/src/main/java/com/example/AddScriptJavaDoc.java @@ -0,0 +1,28 @@ +package com.example; + +/* + * 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. + */ + +/** + * Support for multiple extra scripts + */ +public class AddScriptJavaDoc +{ + +} diff --git a/src/it/projects/addscript/src/main/javadoc/resources/custom-script.js b/src/it/projects/addscript/src/main/javadoc/resources/custom-script.js new file mode 100644 index 000000000..3d5ae068a --- /dev/null +++ b/src/it/projects/addscript/src/main/javadoc/resources/custom-script.js @@ -0,0 +1,20 @@ +/* + * 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. + */ + +console.log('script'); diff --git a/src/it/projects/addscript/src/main/javadoc/resources/custom-script1.js b/src/it/projects/addscript/src/main/javadoc/resources/custom-script1.js new file mode 100644 index 000000000..84033af24 --- /dev/null +++ b/src/it/projects/addscript/src/main/javadoc/resources/custom-script1.js @@ -0,0 +1,20 @@ +/* + * 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. + */ + +console.log('script1'); diff --git a/src/it/projects/addscript/src/main/javadoc/resources/custom-script2.js b/src/it/projects/addscript/src/main/javadoc/resources/custom-script2.js new file mode 100644 index 000000000..bcc787abc --- /dev/null +++ b/src/it/projects/addscript/src/main/javadoc/resources/custom-script2.js @@ -0,0 +1,20 @@ +/* + * 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. + */ + +console.log('script2'); diff --git a/src/it/projects/addscript/verify.groovy b/src/it/projects/addscript/verify.groovy new file mode 100644 index 000000000..5d9152260 --- /dev/null +++ b/src/it/projects/addscript/verify.groovy @@ -0,0 +1,26 @@ +/* + * 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 file = new File( basedir, 'target/reports/apidocs/com/example/AddScriptJavaDoc.html' ); + +assert file.exists() + +assert 1 == file.text.count('custom-script.js') +assert 1 == file.text.count('custom-script1.js') +assert 1 == file.text.count('custom-script2.js') 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 1981bed20..7b740ace1 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java @@ -1310,6 +1310,22 @@ public AbstractJavadocMojo( @Parameter private String[] addStylesheets; + /** + * Specifies the path of an additional script file relative to the {@code javadocDirectory} + * Example: + * 
+     *     <addScripts>
+     *         <addScript>resources/script.js</addScript>
+     *     </addScripts>
+     *
+ *

+ * These script files are passed to the Javadoc tool via the {@code --add-script} parameter. + * This option is available since JDK 18. + * @since 3.13.0 + */ + @Parameter + private String[] addScripts; + /** * Specifies the class file that starts the taglet used in generating the documentation for that tag. * @see Doclet option taglet. @@ -2789,6 +2805,44 @@ private Optional getAddStylesheet(final File javadocOutputDirectory, final "additional stylesheet file does not exist: " + addstylesheetfile.getAbsolutePath()); } + private void addAddScripts(List arguments) throws MavenReportException { + if (addScripts == null) { + return; + } + + JavaVersion requiredJavaVersionForScripts = JavaVersion.parse("18"); + if (!isJavaDocVersionAtLeast(requiredJavaVersionForScripts)) { + throw new MavenReportException( + "the javadoc tool option to add scripts (--add-scripts) is available only since JDK 18"); + } + + for (String addScript : addScripts) { + Optional script = getAddScript(getJavadocDirectory(), addScript); + + if (script.isPresent()) { + addArgIfNotEmpty( + arguments, + "--add-script", + JavadocUtil.quotedPathArgument(script.get().getAbsolutePath()), + requiredJavaVersionForScripts); + } + } + } + + private Optional getAddScript(final File javadocOutputDirectory, final String script) + throws MavenReportException { + if (script == null || script.isEmpty()) { + return Optional.empty(); + } + + File scriptFile = new File(getJavadocDirectory(), script); + if (scriptFile.exists()) { + return Optional.of(scriptFile); + } + + throw new MavenReportException("script file does not exist: " + scriptFile.getAbsolutePath()); + } + /** * Method to get the help file to be used by the Javadoc Tool. *
@@ -4761,6 +4815,8 @@ private void addStandardDocletOptions( addAddStyleSheets(arguments); + addAddScripts(arguments); + addArgIfNotEmpty(arguments, "-subpackages", subpackages); addArgIfNotEmpty(arguments, "-taglet", JavadocUtil.quotedArgument(taglet));