Deprecate API that uses javax.lang.model.type and java.lang.reflect

[Egorand]

We track a number of issues that stem from the fact that introspecting Kotlin code through mirrors or reflection is unreliable (#86, #236, #828). Now that there's proper support for processing @Metadata, existing API that has been ported from JavaPoet needs to be deprecated and eventually removed in 2.0. We might need to look into providing more documentation or migration recipes.

[Egorand]

I think Zac put it perfectly here:

In short: cases like TypeMirror.asTypeName() or Type.asTypeName() will never work as intended for Kotlin compiler intrinsic types. APIs like this simply cannot look at individual types in isolation and have enough context to understand them. You must have access to the appropriate metadata that describes them in context. There are no silver bullets here, this is how Kotlin works.

[ZacSweers]

What would the scope of this be? I think it makes sense for cases like overriding but for plain old String::class.asTypeName() is fine. The problem is narrowing it down for intrinsic types, where we may want to check at runtime and ask them to explicitly declare which type to use?

[Egorand]

I don't think fixing these APIs is the right solution since the safest APIs still are Metadata-based. Of course in an out-of-context snippet of code it's easier to do asTypeName() than to navigate up to find Metadata, but this is unsafe and will yield incorrect results.

[Egorand]

Fixed by #919