codegen-java: Support generating @Nullable annotations
- Dominant language
- Java
- Stars
- 11.5k
- Forks
- 402
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 20
Description
Motivation:
codegen-java already supports generating `@NonNull` annotations.
However, many projects prefer `@Nullable` over `@NonNull` annotations.
JSpecify also recommends `@Nullable`.
Changes:
- Add a `--nullable-annotation` CLI parameter that defaults to `none`.
- Add a `nullableAnnotation` Gradle/CliJavaCodeGenerator/JavaCodeGenerator property that defaults to `null`.
- Annotate nullable types with the configured annotation (if any).
As part of this feature, I propose to also make the following changes:
- Change the `-non-null-annotation` CLI parameter and `nonNullAnnotation` properties accordingly.
- Do not generate `@NonNull` annotations by default.
- Deprecate `org.pkl.java.config.mapper.NonNull` and encourage users to switch to JSpecify.
Note that tools won't recognize `org.pkl.java.config.mapper.NonNull` unless explicitly configured.
Open question:
`@Nullable` must be accompanied by `@NullMarked` (JSpecify) or `@NonnullByDefault` (JSR 305).
I can think of two ways to go about this:
1. Introduce `--null-marked-annotation` and annotate config classes accordingly.
This is the most consistent solution, but it requires yet another CLI parameter and property.
It can be made more convenient by inferring the correct annotation based on `--nullable-annotation` and `--non-null-annotation` for popular libraries such as JSpecify and JSR 305.
2. Leave it to users to add a `package-info.java` with a `@NullMarked` annotation.
This is a clean and simple solution. However, it is less convenient than (1).
It could, in theory, cause problems if users compile generated and handwritten code separately and don't have a place where to put `package-info.java`.
Final thought: The Java ecosystem is converging on JSpecify. For many users, the best option would be `--generate-jspecify-annotations`.
Contributor guide
Research direction
Start with the codegen-java implementation and the CLI/Gradle/CliJavaCodeGenerator/JavaCodeGenerator property definitions, then trace the existing @NonNull generation. Define how nullable types and default annotation settings should be represented, including whether null-marking is configured or left to users; done requires the CLI and properties to support nullable annotations and the generated Java output to apply them consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100