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.

Sign up for GitHub

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

Jump to bottom

RFC: Fix some javadoc issues #3509

Merged
merged 1 commit into from
Oct 31, 2024
Merged

RFC: Fix some javadoc issues #3509

merged 1 commit into from
Oct 31, 2024

Conversation

rPraml
Copy link
Contributor

@rPraml rPraml commented Oct 25, 2024

When running a maven build, I get

[WARNING] Some problems were encountered while building the effective model for io.ebean:ebean-core:jar:14.8.0
[WARNING] 'build.plugins.plugin.version' for org.apache.maven.plugins:maven-javadoc-plugin is missing. @ line 238, column 15
[WARNING]
[WARNING] It is highly recommended to fix these problems because they threaten the stability of your build.
[WARNING]
[WARNING] For this reason, future Maven versions might no longer support building such malformed projects.

Then I get

[INFO] The goal 'org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc' has not been previously called for the module: 'io.ebean:ebean-api:jar:14.8.0'. Trying to invoke it...
[ERROR] MavenInvocationException: Error when invoking Maven, consult the invoker log file: /home/roland/dev/ebean/ebean-core/target/invoker/maven-javadoc-plugin1392421445.txt
[INFO] The goal 'org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc' has not been previously called for the module: 'io.ebean:ebean-core-type:jar:14.8.0'. Trying to invoke it...
[INFO] The goal 'org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc' has not been previously called for the module: 'io.ebean:ebean-platform-h2:jar:14.8.0'. Trying to invoke it...
[INFO] The goal 'org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc' has not been previously called for the module: 'io.ebean:ebean-platform-postgres:jar:14.8.0'. Trying to invoke it...
[INFO] The goal 'org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc' has not been previously called for the module: 'io.ebean:ebean-platform-sqlserver:jar:14.8.0'. Trying to invoke it...

In the invoker log, there I find

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.10.1:javadoc (default-cli) on project ebean-api: An error has occurred in Javadoc report generation:
[ERROR] Exit code: 1
[ERROR] /home/roland/dev/ebean/ebean-api/src/main/java/io/ebean/ScriptRunner.java:9: error: self-closing element not allowed
[ERROR]  * <p/>

rPraml
rPraml commented Oct 25, 2024
View reviewed changes
ebean-api/src/main/java/io/ebean/DatabaseBuilder.java
* Controls if Ebean should ignore <code>&x64;javax.validation.contstraints.NotNull</code> or
* <code>&x64;jakarta.validation.contstraints.NotNull</code>
* Controls if Ebean should ignore <code>&#64;javax.validation.contstraints.NotNull</code> or
* <code>&#64;jakarta.validation.contstraints.NotNull</code>
* with respect to generating a <code>NOT NULL</code> column.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is obviously wrong

ebean-core/pom.xml
@@ -239,7 +239,7 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<doctitle>Ebean 12</doctitle>
<doctitle>Ebean 14</doctitle>
<overview>src/main/java/io/ebean/overview.html</overview>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This configuration is not used, when javadoc is called for other modules (javadoc' has not been previously called for the module: 'io.ebean:ebean-api:jar)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this can be removed really. Good catch.

pom.xml
@@ -56,6 +56,7 @@
<ebean-agent.version>14.8.0</ebean-agent.version>
<ebean-maven-plugin.version>14.8.0</ebean-maven-plugin.version>
<surefire.useModulePath>false</surefire.useModulePath>
<maven-javadoc-plugin.version>3.10.1</maven-javadoc-plugin.version>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

java11-oss defines 3.7.0 (but both versions have the same problem)

pom.xml
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin.version}</version>
<configuration>
<additionalOptions>-Xdoclint:none</additionalOptions>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is, that there are many javadocs, that uses non-HTML4-compliant tags.
I don't know, what's the best here. Change the HTML5 tags (that obviously work in the browser) to HTML4 tags or disable linting in ebean-paren (or only in specific module)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. disable linting seems reasonable for now.

rbygrave
rbygrave approved these changes Oct 31, 2024
View reviewed changes
ebean-core/pom.xml
@@ -239,7 +239,7 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<doctitle>Ebean 12</doctitle>
<doctitle>Ebean 14</doctitle>
<overview>src/main/java/io/ebean/overview.html</overview>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this can be removed really. Good catch.

pom.xml
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin.version}</version>
<configuration>
<additionalOptions>-Xdoclint:none</additionalOptions>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. disable linting seems reasonable for now.

@rbygrave rbygrave merged commit 9f5a77f into ebean-orm:master Oct 31, 2024
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rbygrave rbygrave rbygrave approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@rPraml @rbygrave