Java: Make it more explicit when CodeQL classes and predicates only apply to Kotlin

[Marcono1234]

For multiple CodeQL classes (and possibly predicates) for Java / Kotlin it is not obvious that they only apply to Kotlin. This makes it difficult to read the documentation and decide if you have to specially treat a certain CodeQL class, or even what the CodeQL class represents in the first place.

A good (negative) example for this is PropertyRefExpr. Neither the name nor the documentation give any indication that this is Kotlin-specific. You can only guess this if you have used Kotlin before and the term "property" in combination with "get" and "set" sound familiar.

Some Kotlin-specific classes seem to be prefixed with Kotlin or Kt (see index), but this is not consistent.

I assume this general issue might affect other languages supported by CodeQL as well, such as C / C++ and JavaScript / TypeScript.

Maybe it would be useful if CodeQL QLDoc comments supported some kind of "tag" which would be shown in the documentation whenever the name of the class or predicate is displayed, similar to how the Javadoc displays Preview features (see for example Java 21 FormatProcessor).
Or alternatively it would be good if a certain prefix such as "Kt" would be used consistently.

What do you think?

[aibaars]

Thanks for reporting. It's a good idea. I'll let the team know, but it may be quite a while before this gets addressed (if at all) because it potentially involves changes in many languages.

[igfoo]

Thanks for raising this.

The history is: Our general approach for Kotlin was to share classes with Java wherever possible, so in general there is no language qualifier (e.g. for AddExpr). For consistency, we didn't add any qualifier when adding new constructs that are Kotlin-only. However, sometimes we needed a different Kotlin class for a construct that already existed for Java, so we added a prefix.

I agree we should be consistent in which prefix we use. Kotlin is probably better in my opinion, as Kt may be harder to decipher for people looking from a Java-only perspective.

I'm not sure if prefixing everything that is Kotlin-only would be better. For one thing we don't prefix any Java-only classes. For another, it is possible that Java will adopt features that are currently Kotlin-only. Although it is also possible that Java will get variants of those features that are incompatible with Kotlin. In any case, we should make a decision on which way we want to go here.

But at least documenting that features are Kotlin-only or Java-only would make sense.