Position of JSpecify annotations on fields

[simasch]

With version 0.0.46 (I assume it's because of #442) the JSpecify annotations are now on the same line as the field declaration. When using other field annotations, this results in a mix:

@NotBlank
private String lastName;

@NotNull
private String market;

@Nullable private String picture;

Is this really what you wanted to achieve with this update?

[bclozel]

Yes, I think that is the intent. JSpecify annotations are "type-use annotations", meaning they don't apply to a method or a field, but rather to the return type, parameter type or field type.

[simasch]

@bclozel The question is not about whether it's correct to use JSpecify annotation on fields. It's about where the annotation should be placed and why it's different for JSpecify annotations and Jakarta Validation annotations.
This is a formatting questiion.

[bclozel]

@simasch Understood. I was providing the rationale behind that intent. Let's zoom a bit, then.

Jakarta Validation annotations have "method", "field", "contructor"... as targets (also "type_use", but I'm not seeing them being used like that often). Java developers usually use such annotations on a different line, like:

@NotBlank
private String lastName;

JSpecify annotations are "type_use" only. As far as I understand, the compiler doesn't really make a difference at the source level, but it has strong implications for the annotation itself.

As you can see in the JSpecify docs I linked earlier, you can have multiple @Nullable annotations per field:

private @Nullable String @Nullable [] names; // both the array and its elements can be null

I understand that this feels a bit unusual at first, but this nuance is really important.
If we don't enforce this, we could end up with the following, which in my opinion is confusing even more.

@Nullable
private String @Nullable [] names; // both the array and its elements can be null

What do you think?

[simasch]

@bclozel Now I understand! Thanks a lot for the clarification.
I think it would be useful to mention this in the documentation, as I expect other developers may have the same question.

[bclozel]

I don't see an obvious place in the README of this project to document that. We don't even mention annotations there.
I think the Spring Framework reference docs are already providing a lot of information about JSpecify annotations. Maybe we can add a note there to disambiguate. I think developers would naturally check out Spring Framework's reference docs before this project if they're adopting JSpecify annotations in their project.

I've created spring-projects/spring-framework#35098