Skip to content

Commit

Permalink
Don't use groovy to generate javadoc
Browse files Browse the repository at this point in the history
This adds a package-info.class file to the generated jar but it shouldn't be a problem
This is because maven uses the jar as the input to the javadoc tool and we don't
want to diverge too much from the maven way (you get problems really fast)
(In theory, I guess we could generated the javadoc from target/classes instead of target/project.jar)

The generated javadoc has one package with one class because:
- It doesn't seem to be possible to generate an empty javadoc (no packages).
- It doesn't seem to be possible to generate an empty package (no classes).

references:
* https://stackoverflow.com/questions/53706943/how-to-upload-an-artifact-to-maven-central-with-an-empty-javadoc-jar-or-empty-s
 => what we did in 1.0.0 and 1.0.1: totally empty javadoc.jar (valid for maven central upload but ugly)
* https://stackoverflow.com/questions/59071851/how-to-force-a-javadoc-jar-even-though-there-is-no-public-javadoc
 => still produces a totally empty javadoc.jar (and big scary red errors)
* https://stackoverflow.com/questions/1138390/javadoc-for-package-info-java-only
 => This plus excluding the class from the jar seems like the best solution for now ?

promising but not yet ready:
* https://issues.apache.org/jira/browse/MJAVADOC-329
  apache/maven-javadoc-plugin#65
* https://bugs.openjdk.org/browse/JDK-8193107
  https://hg.openjdk.org/jdk/jdk/rev/111104f1e033
  empty modules are allowed, but does becoming a module work with how the native library are loaded ??
  • Loading branch information
jonenst committed Aug 31, 2023
1 parent 66459e6 commit dc778b7
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 19 deletions.
24 changes: 5 additions & 19 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<parent>
<groupId>com.powsybl</groupId>
<artifactId>powsybl-parent</artifactId>
<version>3</version>
<version>14</version>
<relativePath/>
</parent>

Expand Down Expand Up @@ -46,13 +46,6 @@
</developer>
</developers>

<properties>
<maven.build-helper.version>3.1.0</maven.build-helper.version>

<groovy.version>2.5.8</groovy.version>
<groovydoc.classifier>javadoc</groovydoc.classifier>
</properties>

<build>
<plugins>
<plugin>
Expand All @@ -64,17 +57,11 @@
<Automatic-Module-Name>com.powsybl.mathnative</Automatic-Module-Name>
</manifestEntries>
</archive>
<excludes>
<exclude>com/powsybl/mathnative/MathNativeJavadocPlaceholder.class</exclude>
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${maven.build-helper.version}</version>
</plugin>
</plugins>
</build>

Expand All @@ -89,10 +76,9 @@
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${maven.build-helper.version}</version>
<executions>
<execution>
<id>add-source</id>
<id>add-cpp-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
Expand Down
4 changes: 4 additions & 0 deletions src/com/powsybl/mathnative/MathNativeJavadocPlaceholder.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
package com.powsybl.mathnative;

/** Placeholder needed by the javadoc tool to generate the javadoc site */
public class MathNativeJavadocPlaceholder { private MathNativeJavadocPlaceholder() { } }
2 changes: 2 additions & 0 deletions src/com/powsybl/mathnative/package-info.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/** Native library binaries for powsybl math operations */
package com.powsybl.mathnative;

0 comments on commit dc778b7

Please sign in to comment.