Adding custom annotations to UnstableApiUsageInspection
Hi,
I'm developing an IntelliJ plugin for our company internal framework and we are using an annotation to mark internal / experimental API so that clients are aware that some API is not endorsed by us. I stumbled upon UnstableApiUsageInspection which reports "[...] usages of API marked with "unstable" annotations from the list below." Is there a way that a custom plugin can add to that list of marked annotations?
I know that I can tell users to add the annotation manually in the IntelliJ configuration (via the Inspection configuration tab you can add custom annotations), but I'd rather do that automatically for them if possible. My other idea was to make a copy of the existing Inspection and customize it to my needs if there is no way to extend the existing one.
As a sidenote - is it expected that this UnstableApiUsageInspection is not working at all for Groovy classes (even with the @CompileStatic) annotation? I find this interesting since technically it seems to be possible to do as e.g. the GrDeprecatedAPIUsageInspection showcases (however just for @Deprecated annotations).
Thanks for helping!!
请先登录再写评论。
Hi, schneida!
Thanks for bringing up this question!
1) "Unstable API usage" inspection originally works only for APIs that declared in included libraries. If a class in your source code base is marked with an "unstable" annotation, the inspection won't produce a warning. There is the suggestion to make it work for sources, too: https://youtrack.jetbrains.com/issue/IDEA-237242
2) If it worked, there wouldn't be need to contribute annotation via plugin. It is enough to add a new annotation in the inspection profile's settings and save `.idea/inspectionProfiles/idea_default.xml` to VCS of the project. All developers would have this inspection properly configured then.
3) Groovy inspections historically do not reuse Java's inspections, so some functionality may be missing. I've filed a ticket to unify them: https://youtrack.jetbrains.com/issue/IDEA-241315
You told about a custom plugin for the company. I'd like to clarify the following questions to estimate how soon we can address your use case:
1) What is the IDE compatibility range of the plugin (since-until build specified in plugin.xml), or in other words: what is the minimum supported IDE build your colleagues use?
2) Is the plugin published to https://plugins.jetbrains.com? If it is, we can do our best to not break API compatiblity with the plugin in new IDE builds.
As for the possible solution for now. Unfortunately, the easiest way is to create your own inspection based on `UnstableApiUsageInspection` implementation, and fix the "libraries-only" issue in it (it must be as simple as removing one "if-condition").
Note that it's rather hard to properly handle all syntax constructs of Java/Kotlin/Groovy code where an "unstable" API may be encountered. The current implementation uses so-called `ApiUsageUastVisitor` with custom `ApiUsageProcessor`, which have all (or most of) the cases handled. It is marked with `@ApiStatus.Experimental` because its API can be changed in the future and possibly break API compatibility (although for this concrete interface it is unlikely).
If you decide to copy this inspection, I suggest that you watch the original ticket https://youtrack.jetbrains.com/issue/IDEA-237242: as soon as it is available in a new IDE release, you can reuse it and remove your own implementation.
Feel free to ask additional questions!
Hey,
many thanks for the prompt and very helpful reply!
The limitation of the current inspection only applying to dependencies is actually perfect for us. Our clients use our framework as maven dependency in their own projects and as such the inspection (when configured manually to include our annotation) works just fine.
Am I right to assume your comment about adding the annotation to ".idea/inspectionProfiles/idea_default.xml" only applies if we were all using a shared IntelliJ workspace and there is no way of our custom plugin to add to this setting file to enable our custom annotation for the UnstableApiUsageInspection?
Regarding the plugin:
1) currently we target 2019.2.4 as minimum version (as set in the gradle build file)
2) Sadly it's not published to the official repository, maybe in the future if it's useful for external clients too
3) I think for now we go with the copying of the existing inspection and will simply have to be careful in case there are changes to the API we are using.
Thanks again for your support!
You are welcome!
Currently, new annotations can be added to the list only in the inspection's profile settings. I agree that it may be useful to have an extension point for this, filed this ticket: https://youtrack.jetbrains.com/issue/IDEA-241382