Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MJAVADOC-697] Allowing to register alternative Javadoc implementation #106

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

dukescript
Copy link

@dukescript dukescript commented Oct 28, 2021

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!

  • [ x ] Addressing MJAVADOC-697
  • [ x ] Each commit in the pull request should have a meaningful subject line and body.
  • [ x ] Format the pull request title like [MJAVADOC-XXX]
  • [ x ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • [ x ] Run mvn clean verify -Prun-its to make sure basic checks pass. A more thorough check will
    be 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.

@dukescript
Copy link
Author

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>

@dukescript
Copy link
Author

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 mvn javadoc:javadoc fails with:

Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.1.1:javadoc (default-cli) on project frgaaldoc: An error has occurred in Javadoc report generation: 
Exit code: 1 - src/main/java/frgaaldoc/demo/frgaaldoc/Main.java:6: error: unclosed string literal
        var x = """
                  ^
main/java/frgaaldoc/demo/frgaaldoc/Main.java:7: error: ';' expected
        Hello World!    
                   ^
src/main/java/frgaaldoc/demo/frgaaldoc/Main.java:8: error: unclosed string literal
        """;
          ^

with the change proposed by this PR the Javadoc can be generated without issues. Can you consider introduction of org.apache.maven.plugins.javadoc.JavadocImplementation or similar concept? It would help these alternative Java compilers a lot!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant