[MJAVADOC-697] Allowing to register alternative Javadoc implementation #106
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
With this change one can write a plugin extension to bind it all together: diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000..f0d9f1f
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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>
+
+ <properties>
+ <maven.compiler.source>1.8</maven.compiler.source>
+ <maven.compiler.target>1.8</maven.compiler.target>
+ </properties>
+
+ <groupId>org.frgaal</groupId>
+ <artifactId>javadoc-maven-plugin</artifactId>
+ <version>16.0.1</version>
+ <packaging>jar</packaging>
+
+ <name>frgaal Maven Javadoc </name>
+ <description>frgaal Javadoc support.</description>
+ <url>http://frgaal.org</url>
+
+ <licenses>
+ <license>
+ <name>The Apache Software License, Version 2.0</name>
+ <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
+ <distribution>repo</distribution>
+ </license>
+ </licenses>
+
+ <developers>
+ <developer>
+ <name>frgaal Developer</name>
+ <email>frgaal@frgaal.org</email>
+ </developer>
+ </developers>
+
+ <scm>
+ <connection>scm:git:git://github.com/frgaal/javadoc-maven-plugin.git</connection>
+ <developerConnection>scm:git:ssh://github.com:frgaal/javadoc-maven-plugin.git</developerConnection>
+ <url>http://github.com/frgaal/javadoc-maven-plugin/tree/master</url>
+ </scm>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-source-plugin</artifactId>
+ <version>3.2.1</version>
+ <executions>
+ <execution>
+ <id>attach-sources</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>3.1.1</version>
+ <executions>
+ <execution>
+ <id>attach-javadocs</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.frgaal</groupId>
+ <artifactId>javadoc</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-component-annotations</artifactId>
+ <version>2.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-container-default</artifactId>
+ <version>2.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>3.1.1</version>
+ </dependency>
+ </dependencies>
+</project>
diff --git a/src/main/java/org/frgaal/maven/javadoc/FrgaalJavadocImplementation.java b/src/main/java/org/frgaal/maven/javadoc/FrgaalJavadocImplementation.java
new file mode 100644
index 0000000..43c591b
--- /dev/null
+++ b/src/main/java/org/frgaal/maven/javadoc/FrgaalJavadocImplementation.java
@@ -0,0 +1,38 @@
+package org.frgaal.maven.javadoc;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.util.ArrayList;
+import java.util.List;
+import org.apache.maven.plugins.javadoc.JavadocImplementation;
+import org.codehaus.plexus.component.annotations.Component;
+import org.codehaus.plexus.util.cli.CommandLineUtils;
+import org.codehaus.plexus.util.cli.Commandline;
+
+@Component(role = JavadocImplementation.class)
+public class FrgaalJavadocImplementation implements JavadocImplementation {
+ @Override
+ public int execute(Commandline cmd, CommandLineUtils.StringStreamConsumer out, CommandLineUtils.StringStreamConsumer err) {
+ StringWriter outData = new StringWriter();
+ StringWriter errData = new StringWriter();
+ List<String> arguments = new ArrayList<>();
+ //absolutize '@' arguments:
+ //TODO: Windows paths handling!
+ for (String arg : cmd.getArguments()) {
+ if (arg.startsWith("@") && !arg.startsWith("@/")) {
+ arguments.add("@" + cmd.getWorkingDirectory().getAbsolutePath() + "/" + arg.substring(1));
+ } else {
+ arguments.add(arg);
+ }
+ }
+ int exitCode = org.frgaal.javadoc.Main.execute(arguments.toArray(new String[0]), new PrintWriter(outData), new PrintWriter(errData));
+ for (String outLine : outData.toString().split("\n")) {
+ out.consumeLine(outLine);
+ }
+ for (String errLine : errData.toString().split("\n")) {
+ err.consumeLine(errLine);
+ }
+ return exitCode;
+ }
+
+}
diff --git a/src/main/resources/META-INF/plexus/components.xml b/src/main/resources/META-INF/plexus/components.xml
new file mode 100644
index 0000000..732d748
--- /dev/null
+++ b/src/main/resources/META-INF/plexus/components.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component-set>
+ <components>
+ <component>
+ <role>org.apache.maven.plugins.javadoc.JavadocImplementation</role>
+ <role-hint>frgaal</role-hint>
+ <implementation>org.frgaal.maven.javadoc.FrgaalJavadocImplementation</implementation>
+ <description />
+ <isolated-realm>false</isolated-realm>
+ </component>
+ </components>
+</component-set> |
|
and finally use it as: diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000..6b533c4
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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>frgaaldoc.demo</groupId>
+ <artifactId>frgaaldoc</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <maven.compiler.source>16</maven.compiler.source>
+ <maven.compiler.target>8</maven.compiler.target>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.8.1</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.frgaal</groupId>
+ <artifactId>compiler-maven-plugin</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <compilerId>frgaal</compilerId>
+ <source>16</source>
+ <target>1.8</target>
+ <compilerArgs>
+ <arg>-Xlint:deprecation</arg>
+ </compilerArgs>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>3.1.1</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.frgaal</groupId>
+ <artifactId>javadoc-maven-plugin</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
\ No newline at end of file
diff --git a/src/main/java/frgaaldoc/demo/frgaaldoc/Main.java b/src/main/java/frgaaldoc/demo/frgaaldoc/Main.java
new file mode 100644
index 0000000..0090185
--- /dev/null
+++ b/src/main/java/frgaaldoc/demo/frgaaldoc/Main.java
@@ -0,0 +1,12 @@
+package frgaaldoc.demo.frgaaldoc;
+
+/** A class using text blocks */
+public class Main {
+ public static void main(String[] args) {
+ var x = """
+ Hello World!
+ """;
+
+ System.err.println(x);
+ }
+}without the change in this PR the with the change proposed by this PR the Javadoc can be generated without issues. Can you consider introduction of |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The Maven compiler plugin allows different implementations of compilers to plug in. One of the very useful ones is the retrofit compiler for Java that allows one to use syntax of JDK-16 while running on old JDKs.
The compiler works fine, however the problem comes when one wants to generate Javadoc. Because the source code is using newer language constructs, classical javadoc from old JDKs fails. One either has to generate the Javadoc on a newest JDK (which beats the purpose of retrofit compiler) or give up on Javadoc. Or...
Let's enhance the Maven Javadoc Plugin to support alternative implementations of Javadoc, just like the Maven Compiler Plugin does with compilers!
[MJAVADOC-XXX]mvn clean verify -Prun-itsto make sure basic checks pass. A more thorough check willbe performed on your pull request automatically.
Pull request is about ~20 lines of code - no need to sign an Individual Contributor License Agreement. To make clear that you license your contribution under the Apache License Version 2.0, January 2004 you have to acknowledge this by using the following check-box.