JSR-305 custom nullability qualifiers #78
Conversation
| } | ||
|
|
||
| @Target(AnnotationTarget.ANNOTATION_CLASS) | ||
| annotation class Migration(val status: MigrationStatus) |
There was a problem hiding this comment.
Why such a generic name? Is it supposed to be used for something else in the future?
There was a problem hiding this comment.
If yes, maybe it makes sense to rename -Xjsr305-annotation-migration to something like -Xoverride-migration-status
There was a problem hiding this comment.
The name is a subject for discussion as usual, but the flag name you proposed seems to be more appropriate here
There was a problem hiding this comment.
I mean, what other use cases for this annotation were considered?
If none were, then it probably should reflect that it's about JSR-305 in its name, e.g. kotlin.jvm.Jsr305Migration, and the compiler argument should indeed be named something like -Xjsr305-annotation-migration.
| to `ERROR`, then it should become an error. | ||
|
|
||
| It's important that migration annotation works only for its immediate usages | ||
| on types or through `TypeQualifierDefault` annotation. |
There was a problem hiding this comment.
It says above
it can be only used for custom nullability qualifier nicknames
, so this line is a bit confusing. Can I use it with TypeQualifierDefault or not? Maybe provide an example
| When determining immediate nullability of a type the Kotlin compiler should look | ||
| for nullability annotation on the type itself at first. | ||
| - If there is one, then it should use it | ||
| - Otherwise, nullability is determined by the closest annotation marked as |
There was a problem hiding this comment.
It may be unclear to users what "closest" means here
There was a problem hiding this comment.
@udalov How do you think, would the phrase "the innermost enclosing element annotated with TypeQualifierDefault" be more clear in the context?
| It effectively defines the migration status behavior only for nullability | ||
| qualifier nicknames that haven't yet been annotated with `kotlin.Migration`. | ||
|
|
||
| This annotation is necessary, since using all of the custom nullability |
There was a problem hiding this comment.
This annotation -> This compiler flag?
I can't make sense of this sentence either way though
There was a problem hiding this comment.
Of course, it's all about the compiler flag
This sentence is intended to describe the motivation behind its introduction (a lot of already annotated API that we haven't processed properly until now)
| Sometimes it might be necessary to manage a migration phase for a particular | ||
| library. That could be done with the flag `-Xjsr305-user-annotation`. It | ||
| accepts fully-qualified name of a nullability qualifier annotation and its | ||
| desired status in a format `<fq.name>:ignore/warn/error`. |
There was a problem hiding this comment.
Please provide a concrete usage example of this compiler argument here in the proposal
| Current proposal is supposed to introduce additional ways of types enhancement | ||
| and instruments to control their migration status. | ||
|
|
||
| ### Type qualifier nicknames |
There was a problem hiding this comment.
This part is very hard to understand for people having no background in how JSR-305 is supposed to work. Given that there's no comprehensive doc on JSR-305, I think we should include a brief description of its relevant parts
There was a problem hiding this comment.
Having read a bit further, I realize that this part is giving the necessary background, but it's not clear upfront. We should add a comment on this, along the lines of "JSR 305 has this and that semantics, and we support the following part of it"
| corresponding `when` argument. Namely: | ||
| - `When.ALWAYS` makes the type not-nullable | ||
| - `When.MAYBE` makes the type nullable | ||
| - `When.NEVER/When.UNKNOWN` doesn't affect type's nullability |
There was a problem hiding this comment.
Why do we treat NEVER this way?
| Current proposal is supposed to introduce additional ways of types enhancement | ||
| and instruments to control their migration status. | ||
|
|
||
| ### Type qualifier nicknames |
There was a problem hiding this comment.
Having read a bit further, I realize that this part is giving the necessary background, but it's not clear upfront. We should add a comment on this, along the lines of "JSR 305 has this and that semantics, and we support the following part of it"
| - `ElementType.METHOD` for return type of methods | ||
| - `ElementType.PARAMETER` for value parameters | ||
| - `ElementType.FIELD` for fields | ||
| - `ElementType.TYPE_USE` for any top-level type |
|
|
||
| Note, that `javax.annotation.ParametersAreNonnullByDefault` annotation should | ||
| work automatically | ||
| by applying the rules above. |
There was a problem hiding this comment.
It would be great to include its declaration here
There was a problem hiding this comment.
And a link to its JavaDoc or some other description would be great too
| } | ||
| ``` | ||
| ```java | ||
| // FILE: test/package-info.java |
There was a problem hiding this comment.
I'd suggest to put each file in a separate code block
| ### `@Migration` annotation | ||
| Current proposal suggests to add the following meta-annotation in | ||
| the `kotlin.annotation` package: | ||
| ```kotlin |
There was a problem hiding this comment.
I'd add a package statement here too
|
|
||
| ### `@Migration` annotation | ||
| Current proposal suggests to add the following meta-annotation in | ||
| the `kotlin.annotation` package: |
There was a problem hiding this comment.
Did we discuss the package much? Looks like it should be something jvm-specific, e.g. kotlin.annotation.jvm
|
|
||
| Its aim is to define a migration status of an annotation it's been applied to. | ||
| To the moment it can be only used for custom nullability qualifier | ||
| [nicknames](#Type qualifier nicknames) introduced in this proposal as well. |
|
|
||
| When the annotation is applied to a nullability nickname its argument specifies | ||
| how the compiler handles the nickname: | ||
| - `MigrationStatus.ERROR` makes annotation work just the same way as any plain |
There was a problem hiding this comment.
We need to explain why we need this
| errors | ||
| for | ||
| inappropriate usages of an annotated type | ||
| - `MigrationStatus.IGNORE` makes compiler to ignore the annotation completely |
There was a problem hiding this comment.
It's unclear which annotation is ignored. A motivating use case would help
|
|
||
| ### `@UnderMigration` annotation | ||
| Current proposal suggests to add the following meta-annotation in | ||
| the `kotlin.annotations.jvm` package: |
There was a problem hiding this comment.
You should probably also highlight that it's in a separate library, not in kotlin-stdlib
| custom nullability qualifiers) without `jsr305.jar` as a dependency. | ||
|
|
||
| # Open questions/issues | ||
| - Should nullability default qualifiers with `TYPE_USE` applicability enhance |
There was a problem hiding this comment.
Not an open question anymore, since we agreed to do this?
No description provided.