apple / apple/pkl

codegen-java: Support generating @Nullable annotations

Open
#811 8 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.