Deprecate mirror and element APIs

kotlinpoet/src/main/java/com/squareup/kotlinpoet/AnnotationSpec.kt

@@ -23,6 +23,7 @@ import javax.lang.model.element.TypeElement
 import javax.lang.model.element.VariableElement
 import javax.lang.model.type.TypeMirror
 import javax.lang.model.util.SimpleAnnotationValueVisitor7
+import kotlin.DeprecationLevel.WARNING
 import kotlin.reflect.KClass
 
 /** A generated annotation on a declaration.  */
@@ -222,7 +223,13 @@ class AnnotationSpec private constructor(
       }
     }
 
-    @JvmStatic fun get(annotation: AnnotationMirror): AnnotationSpec {
+    @Deprecated(
+        message = "Mirror APIs don't give complete information on Kotlin types. Consider using" +
+            " the kotlinpoet-metadata APIs instead.",
+        level = WARNING
+    )
+    @JvmStatic
+    fun get(annotation: AnnotationMirror): AnnotationSpec {
       val element = annotation.annotationType.asElement() as TypeElement
       val builder = AnnotationSpec.builder(element.asClassName())
           .tag(annotation)

kotlinpoet/src/main/java/com/squareup/kotlinpoet/ClassName.kt

@@ -23,6 +23,7 @@ import javax.lang.model.element.NestingKind.MEMBER
 import javax.lang.model.element.NestingKind.TOP_LEVEL
 import javax.lang.model.element.PackageElement
 import javax.lang.model.element.TypeElement
+import kotlin.DeprecationLevel.WARNING
 import kotlin.reflect.KClass
 
 @JvmName("get")
@@ -51,6 +52,11 @@ fun KClass<*>.asClassName(): ClassName {
 }
 
 /** Returns the class name for `element`.  */
+@Deprecated(
+    message = "Element APIs don't give complete information on Kotlin types. Consider using" +
+        " the kotlinpoet-metadata APIs instead.",
+    level = WARNING
+)
 @JvmName("get")
 fun TypeElement.asClassName(): ClassName {
   fun isClassOrInterface(e: Element) = e.kind.isClass || e.kind.isInterface

kotlinpoet/src/main/java/com/squareup/kotlinpoet/CodeBlock.kt

@@ -42,8 +42,7 @@ import kotlin.reflect.KClass
  *  * `%P` - Similar to `%S`, but doesn't escape dollar signs (`$`) to allow creation of string
  *    templates. If the string contains dollar signs that should be escaped - use `%S`.
  *  * `%T` emits a *type* reference. Types will be imported if possible. Arguments for types may be
- *    [classes][Class], [type mirrors][javax.lang.model.type.TypeMirror], and
- *    [elements][javax.lang.model.element.Element].
+ *    [classes][Class].
  *  * `%M` emits a *member* reference. A member is either a function or a property. If the member is
  *    importable, e.g. it's a top-level function or a property declared inside an object, the import
  *    will be resolved if possible. Arguments for members must be of type [MemberName].
@@ -363,10 +362,21 @@ class CodeBlock private constructor(
 
     private fun argToString(o: Any?) = o?.toString()
 
+    private fun logDeprecationWarning(o: Any) {
+      println("Deprecation warning: converting $o to TypeName. Conversion of TypeMirror and" +
+          " TypeElement is deprecated in KotlinPoet, use kotlin-metadata APIs instead.")
+    }
+
     private fun argToType(o: Any?) = when (o) {
       is TypeName -> o
-      is TypeMirror -> o.asTypeName()
-      is Element -> o.asType().asTypeName()
+      is TypeMirror -> {
+        logDeprecationWarning(o)
+        o.asTypeName()
+      }
+      is Element -> {
+        logDeprecationWarning(o)
+        o.asType().asTypeName()
+      }
       is Type -> o.asTypeName()
       is KClass<*> -> o.asTypeName()
       else -> throw IllegalArgumentException("expected type but was $o")

kotlinpoet/src/main/java/com/squareup/kotlinpoet/FunSpec.kt

@@ -28,6 +28,7 @@ import javax.lang.model.type.DeclaredType
 import javax.lang.model.type.ExecutableType
 import javax.lang.model.type.TypeVariable
 import javax.lang.model.util.Types
+import kotlin.DeprecationLevel.WARNING
 import kotlin.reflect.KClass
 
 /** A generated function declaration.  */
@@ -506,14 +507,13 @@ class FunSpec private constructor(
 
     @JvmStatic fun setterBuilder() = Builder(SETTER)
 
-    /**
-     * Returns a new fun spec builder that overrides `method`.
-
-     *
-     * This will copy its visibility modifiers, type parameters, return type, name, parameters, and
-     * throws declarations. An `override` modifier will be added.
-     */
-    @JvmStatic fun overriding(method: ExecutableElement): Builder {
+    @Deprecated(
+        message = "Element APIs don't give complete information on Kotlin types. Consider using" +
+            " the kotlinpoet-metadata APIs instead.",
+        level = WARNING
+    )
+    @JvmStatic
+    fun overriding(method: ExecutableElement): Builder {
       var modifiers: Set<Modifier> = method.modifiers
       require(Modifier.PRIVATE !in modifiers &&
           Modifier.FINAL !in modifiers &&
@@ -554,15 +554,13 @@ class FunSpec private constructor(
       return funBuilder
     }
 
-    /**
-     * Returns a new function spec builder that overrides `method` as a member of `enclosing`. This
-     * will resolve type parameters: for example overriding [Comparable.compareTo] in a type that
-     * implements `Comparable<Movie>`, the `T` parameter will be resolved to `Movie`.
-     *
-     * This will copy its visibility modifiers, type parameters, return type, name, parameters, and
-     * throws declarations. An `override` modifier will be added.
-     */
-    @JvmStatic fun overriding(
+    @Deprecated(
+        message = "Element APIs don't give complete information on Kotlin types. Consider using" +
+            " the kotlinpoet-metadata APIs instead.",
+        level = WARNING
+    )
+    @JvmStatic
+    fun overriding(
       method: ExecutableElement,
       enclosing: DeclaredType,
       types: Types

kotlinpoet/src/main/java/com/squareup/kotlinpoet/ParameterSpec.kt

@@ -19,6 +19,7 @@ import java.lang.reflect.Type
 import javax.lang.model.element.ExecutableElement
 import javax.lang.model.element.Modifier
 import javax.lang.model.element.VariableElement
+import kotlin.DeprecationLevel.WARNING
 import kotlin.reflect.KClass
 
 /** A generated parameter declaration.  */
@@ -141,15 +142,27 @@ class ParameterSpec private constructor(
   }
 
   companion object {
-    @JvmStatic fun get(element: VariableElement): ParameterSpec {
+    @Deprecated(
+        message = "Element APIs don't give complete information on Kotlin types. Consider using" +
+            " the kotlinpoet-metadata APIs instead.",
+        level = WARNING
+    )
+    @JvmStatic
+    fun get(element: VariableElement): ParameterSpec {
       val name = element.simpleName.toString()
       val type = element.asType().asTypeName()
       return ParameterSpec.builder(name, type)
           .jvmModifiers(element.modifiers)
           .build()
     }
 
-    @JvmStatic fun parametersOf(method: ExecutableElement) =
+    @Deprecated(
+        message = "Element APIs don't give complete information on Kotlin types. Consider using" +
+            " the kotlinpoet-metadata APIs instead.",
+        level = WARNING
+    )
+    @JvmStatic
+    fun parametersOf(method: ExecutableElement) =
         method.parameters.map { ParameterSpec.get(it) }
 
     @JvmStatic fun builder(name: String, type: TypeName, vararg modifiers: KModifier): Builder {

kotlinpoet/src/main/java/com/squareup/kotlinpoet/TypeName.kt

@@ -36,6 +36,7 @@ import javax.lang.model.type.PrimitiveType
 import javax.lang.model.type.TypeKind
 import javax.lang.model.type.TypeMirror
 import javax.lang.model.util.SimpleTypeVisitor7
+import kotlin.DeprecationLevel.WARNING
 import kotlin.reflect.KClass
 import kotlin.reflect.KTypeProjection
 import kotlin.reflect.KVariance
@@ -273,6 +274,11 @@ sealed class TypeName constructor(
 @JvmField val DYNAMIC = Dynamic
 
 /** Returns a [TypeName] equivalent to this [TypeMirror]. */
+@Deprecated(
+    message = "Mirror APIs don't give complete information on Kotlin types. Consider using" +
+        " the kotlinpoet-metadata APIs instead.",
+    level = WARNING
+)
 @JvmName("get")
 fun TypeMirror.asTypeName() = TypeName.get(this, mutableMapOf())
 

kotlinpoet/src/main/java/com/squareup/kotlinpoet/WildcardTypeName.kt

@@ -18,7 +18,13 @@
 package com.squareup.kotlinpoet
 
 import java.lang.reflect.WildcardType
+import kotlin.DeprecationLevel.WARNING
 
+@Deprecated(
+    message = "Mirror APIs don't give complete information on Kotlin types. Consider using" +
+        " the kotlinpoet-metadata APIs instead.",
+    level = WARNING
+)
 @JvmName("get")
 fun javax.lang.model.type.WildcardType.asWildcardTypeName() =
     WildcardTypeName.get(this, mutableMapOf())