use jakarta.annotation to document nullability of APIs

[gavinking]

see #725

[gavinking]

Setting this to Draft mode because it's a source of conflicts with other open PRs.

[hantsy]

For my opinion, it is better to introduce a @NullMarked or NullUnmarked like JSpecify, or use jspecify to replace the current @Nullable and @Nonnull in jakarta annotation API.

The good is using @NullMarked like annotation on class or package, and assume all parameters/fields/method result default is non null, only need to mark the @Nullable field/results, or in reverse. This way is clearer to use Nullable/Nonnull mixing in the same APIs.

Another benefit from JSpecify is the support from IDE when coding or build tools at compile time.

See: https://jspecify.dev/

[gavinking]

For my opinion, it is better to introduce a @NullMarked or NullUnmarked like JSpecify,

I agree that @NullMarked is nice. But it's highly questionable whether even @Nullable and @Nonnull truly belong in Jakarta Annotations, since Jakarta Annotations isn't a spec for static code analysis, and so I'm not sure we should be doubling down on that by adding @NullMarked as well.

Also, doing that is an invitation to all these people who want to add their favorite rubbishy FindBugs annotations, which would turn Jakarta Annotations into a total mess. Not sure we really want to open that door.

Anyway, @NullMarked isn't in Jakarta Annotations today, so it doesn't help us much right now.

or use jspecify to replace the current @Nullable and @Nonnull in jakarta annotation API.

I'm not sure what you mean by this. JSpecify is an open source library. Jakarta Annotations can't use it.

[hantsy]

Also, doing that is an invitation to all these people who want to add their favorite rubbishy FindBugs annotations, which would turn Jakarta Annotations into a total mess. Not sure we really want to open that door.

There is a JSR-305 for this before.

Currently, Spring and its ecosystem switched to JSpecify, and IDEA also has built-in error/warning reports for JSpecify annotated fields to help developers to avoid NPE.

When using these Spring Java APIs in Kotlin projects, it is type-safe like calling Kotlin types(autodetect the nullable for all fields in a Class, or method parameters) in IDEA.

[gavinking]

There is a JSR-305 for this before.

And that JSR failed.

... for what, it seems to me, after looking at the rather horrible and arbitrary set of proposed annotations, were pretty good reasons, I would say.

Currently, Spring and its ecosystem switched to JSpecify,

Jakarta Persistence is not Spring, and we can't use random libraries we download from the Internet.