xref: /aosp_15_r20/external/kotlinpoet/docs/interop-kotlinx-metadata.md (revision 3c321d951dd070fb96f8ba59e952ffc3131379a0) 
1KotlinPoet-metadata
2===================
3
4`interop:kotlinx-metadata` is an API for working with Kotlin `@Metadata` annotations. Its API
5sits atop [kotlinx-metadata](https://github.com/JetBrains/kotlin/tree/master/libraries/kotlinx-metadata/jvm),
6offering extensions for its types + JVM metadata information. This can be used to read
7Kotlin language semantics off of `Class` or `TypeElement` `@Metadata` annotations.
8
9### Example
10
11```kotlin
12data class Taco(val seasoning: String, val soft: Boolean) {
13  fun prepare() {
14
15  }
16}
17
18val kmClass = Taco::class.toKmClass()
19
20// Now you can access misc information about Taco from a Kotlin lens
21println(kmClass.name)
22kmClass.properties.forEach { println(it.name) }
23kmClass.functions.forEach { println(it.name) }
24```
25
26### Flags
27
28There are a number of boolean flags available to types as well under `Flags.kt`. These read the
29underlying kotlinx-metadata `Flags` property.
30
31Using the Taco example above, we can glean certain information:
32
33```kotlin
34println("Is class? ${kmClass.isClass}")
35println("Is data class? ${kmClass.isData}")
36```
37
38### Interop with KotlinPoet
39
40`interop:kotlinx-metadata` offers an API for converting core kotlinx-metadata `Km` types to
41KotlinPoet source representations of their APIs. This includes full type resolution, signatures,
42enclosed elements, and general stub source representations of the underlying API.
43
44### Example
45
46```kotlin
47data class Taco(val seasoning: String, val soft: Boolean) {
48  fun prepare() {
49  }
50}
51
52val typeSpec = Taco::class.toTypeSpec()
53
54// Or FileSpec
55val fileSpec = Taco::class.toFileSpec()
56```
57
58### Source representation
59
60The generated representations are a _best effort_ representation of the underlying source code.
61This means that synthetic elements will be excluded from generation. Kotlin-specific language
62features like lambdas or delegation will be coerced to their idiomatic source form.
63
64To aid with this, `toTypeSpec()` and `toFileSpec()` accept optional `ClassInspector` instances
65to assist in parsing/understanding the underlying JVM code. This is important for things like
66annotations, companion objects, certain JVM modifiers, overrides, and more. While it is optional,
67represented sources can be incomplete without this information available. Reflective and javax
68`Elements` implementations are available under the
69`com.squareup.kotlinpoet.metadata.classinspectors` package.
70
71Generated sources are solely _stub_ implementations, meaning implementation details of elements
72like functions, property getters, and delegated properties are simply stubbed with `TODO()`
73placeholders.
74
75### Known limitations
76
77- Only `KotlinClassMetadata.Class` and `KotlinClassMetadata.FileFacade` are supported for now. No support for `SyntheticClass`, `MultiFileClassFacade`, or `MultiFileClassPart`
78- `@JvmOverloads` annotations are only supported with `ElementsClassInspector` and not reflection.
79- Non-const literal values are only supported with `ElementsClassInspector` and not reflection.
80- ClassInspector data sourced from `synthetic` constructs are only supported with
81  `ReflectiveClassInspector` and not elements. This is because the javax Elements API does not model
82  synthetic constructs. This can yield some missing information, like static companion object properties
83  or `property:` site target annotations.
84- Annotations annotated with `AnnotationRetention.SOURCE` are not parsable in reflection nor javax elements.
85