Skip to content

Commit

Permalink
Restore ABI stability for annotatable and documentable builders (#1580)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ZacSweers
ZacSweers committed May 29, 2023
1 parent 60491f2 commit 8b2c0fb
Show file tree
Hide file tree
Showing 7 changed files with 216 additions and 12 deletions.
68 changes: 68 additions & 0 deletions kotlinpoet/api/kotlinpoet.api
View file
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,14 @@ public final class com/squareup/kotlinpoet/FileSpec$Builder : com/squareup/kotli
public final fun addAliasedImport (Lkotlin/reflect/KClass;Ljava/lang/String;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/AnnotationSpec;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/AnnotationSpec;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public final fun addBodyComment (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public final fun addCode (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
public final fun addCode (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/FileSpec$Builder;
Expand Down Expand Up @@ -311,9 +319,21 @@ public final class com/squareup/kotlinpoet/FunSpec : com/squareup/kotlinpoet/Ann
}

public final class com/squareup/kotlinpoet/FunSpec$Builder : com/squareup/kotlinpoet/Annotatable$Builder, com/squareup/kotlinpoet/ContextReceivable$Builder, com/squareup/kotlinpoet/Documentable$Builder, com/squareup/kotlinpoet/OriginatingElementsHolder$Builder, com/squareup/kotlinpoet/Taggable$Builder {
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addCode (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addCode (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addComment (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public synthetic fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public synthetic fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addModifiers (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addModifiers ([Lcom/squareup/kotlinpoet/KModifier;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
public final fun addNamedCode (Ljava/lang/String;Ljava/util/Map;)Lcom/squareup/kotlinpoet/FunSpec$Builder;
Expand Down Expand Up @@ -583,6 +603,18 @@ public final class com/squareup/kotlinpoet/ParameterSpec : com/squareup/kotlinpo
}

public final class com/squareup/kotlinpoet/ParameterSpec$Builder : com/squareup/kotlinpoet/Annotatable$Builder, com/squareup/kotlinpoet/Documentable$Builder, com/squareup/kotlinpoet/Taggable$Builder {
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public synthetic fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public synthetic fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public final fun addModifiers (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public final fun addModifiers ([Lcom/squareup/kotlinpoet/KModifier;)Lcom/squareup/kotlinpoet/ParameterSpec$Builder;
public final fun build ()Lcom/squareup/kotlinpoet/ParameterSpec;
Expand Down Expand Up @@ -686,6 +718,18 @@ public final class com/squareup/kotlinpoet/PropertySpec : com/squareup/kotlinpoe
}

public final class com/squareup/kotlinpoet/PropertySpec$Builder : com/squareup/kotlinpoet/Annotatable$Builder, com/squareup/kotlinpoet/ContextReceivable$Builder, com/squareup/kotlinpoet/Documentable$Builder, com/squareup/kotlinpoet/OriginatingElementsHolder$Builder, com/squareup/kotlinpoet/Taggable$Builder {
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public synthetic fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public synthetic fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public final fun addModifiers (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public final fun addModifiers ([Lcom/squareup/kotlinpoet/KModifier;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
public final fun addTypeVariable (Lcom/squareup/kotlinpoet/TypeVariableName;)Lcom/squareup/kotlinpoet/PropertySpec$Builder;
Expand Down Expand Up @@ -766,6 +810,18 @@ public final class com/squareup/kotlinpoet/TypeAliasSpec : com/squareup/kotlinpo
}

public final class com/squareup/kotlinpoet/TypeAliasSpec$Builder : com/squareup/kotlinpoet/Annotatable$Builder, com/squareup/kotlinpoet/Documentable$Builder, com/squareup/kotlinpoet/Taggable$Builder {
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public synthetic fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public synthetic fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public final fun addModifiers (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public final fun addModifiers ([Lcom/squareup/kotlinpoet/KModifier;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
public final fun addTypeVariable (Lcom/squareup/kotlinpoet/TypeVariableName;)Lcom/squareup/kotlinpoet/TypeAliasSpec$Builder;
Expand Down Expand Up @@ -917,12 +973,24 @@ public final class com/squareup/kotlinpoet/TypeSpec : com/squareup/kotlinpoet/An
}

public final class com/squareup/kotlinpoet/TypeSpec$Builder : com/squareup/kotlinpoet/Annotatable$Builder, com/squareup/kotlinpoet/ContextReceivable$Builder, com/squareup/kotlinpoet/Documentable$Builder, com/squareup/kotlinpoet/OriginatingElementsHolder$Builder, com/squareup/kotlinpoet/Taggable$Builder {
public synthetic fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lcom/squareup/kotlinpoet/ClassName;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public synthetic fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Ljava/lang/Class;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public synthetic fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotation (Lkotlin/reflect/KClass;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public synthetic fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/Annotatable$Builder;
public fun addAnnotations (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addEnumConstant (Ljava/lang/String;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addEnumConstant (Ljava/lang/String;Lcom/squareup/kotlinpoet/TypeSpec;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public static synthetic fun addEnumConstant$default (Lcom/squareup/kotlinpoet/TypeSpec$Builder;Ljava/lang/String;Lcom/squareup/kotlinpoet/TypeSpec;ILjava/lang/Object;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addFunction (Lcom/squareup/kotlinpoet/FunSpec;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addFunctions (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addInitializerBlock (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public synthetic fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Lcom/squareup/kotlinpoet/CodeBlock;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public synthetic fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/Documentable$Builder;
public fun addKdoc (Ljava/lang/String;[Ljava/lang/Object;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addModifiers (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addModifiers ([Lcom/squareup/kotlinpoet/KModifier;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
public final fun addProperties (Ljava/lang/Iterable;)Lcom/squareup/kotlinpoet/TypeSpec$Builder;
Expand Down
20 changes: 19 additions & 1 deletion kotlinpoet/src/main/java/com/squareup/kotlinpoet/FileSpec.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,7 @@ public class FileSpec private constructor(
public val name: String,
public val isScript: Boolean,
) : Taggable.Builder<Builder>, Annotatable.Builder<Builder> {
override val annotations: MutableList<AnnotationSpec> = mutableListOf()
internal val comment = CodeBlock.builder()
internal val memberImports = sortedSetOf<Import>()
internal var indent = DEFAULT_INDENT
Expand All @@ -239,7 +240,6 @@ public class FileSpec private constructor(
public val defaultImports: MutableSet<String> = mutableSetOf()
public val imports: List<Import> get() = memberImports.toList()
public val members: MutableList<Any> = mutableListOf()
override val annotations: MutableList<AnnotationSpec> = mutableListOf()
internal val body = CodeBlock.builder()

/**
Expand Down Expand Up @@ -492,6 +492,24 @@ public class FileSpec private constructor(
body.clear()
}

//region Overrides for binary compatibility
@Suppress("RedundantOverride")
override fun addAnnotations(annotationSpecs: Iterable<AnnotationSpec>): Builder =
super.addAnnotations(annotationSpecs)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: ClassName): Builder = super.addAnnotation(annotation)

@DelicateKotlinPoetApi(
message = "Java reflection APIs don't give complete information on Kotlin types. Consider " +
"using the kotlinpoet-metadata APIs instead.",
)
override fun addAnnotation(annotation: Class<*>): Builder = super.addAnnotation(annotation)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: KClass<*>): Builder = super.addAnnotation(annotation)
//endregion

public fun build(): FileSpec {
for (annotationSpec in annotations) {
if (annotationSpec.useSiteTarget != FILE) {
Expand Down
27 changes: 25 additions & 2 deletions kotlinpoet/src/main/java/com/squareup/kotlinpoet/FunSpec.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -308,15 +308,14 @@ public class FunSpec private constructor(
ContextReceivable.Builder<Builder>,
Annotatable.Builder<Builder>,
Documentable.Builder<Builder> {
override val kdoc: CodeBlock.Builder = CodeBlock.builder()
internal var returnKdoc = CodeBlock.EMPTY
internal var receiverKdoc = CodeBlock.EMPTY
internal var receiverType: TypeName? = null
internal var returnType: TypeName = UNIT
internal var delegateConstructor: String? = null
internal var delegateConstructorArguments = listOf<CodeBlock>()
internal val body = CodeBlock.builder()

override val kdoc: CodeBlock.Builder = CodeBlock.builder()
override val annotations: MutableList<AnnotationSpec> = mutableListOf()
public val modifiers: MutableList<KModifier> = mutableListOf()
public val typeVariables: MutableList<TypeVariableName> = mutableListOf()
Expand Down Expand Up @@ -537,6 +536,30 @@ public class FunSpec private constructor(
body.clear()
}

//region Overrides for binary compatibility
@Suppress("RedundantOverride")
override fun addAnnotations(annotationSpecs: Iterable<AnnotationSpec>): Builder =
super.addAnnotations(annotationSpecs)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: ClassName): Builder = super.addAnnotation(annotation)

@DelicateKotlinPoetApi(
message = "Java reflection APIs don't give complete information on Kotlin types. Consider " +
"using the kotlinpoet-metadata APIs instead.",
)
override fun addAnnotation(annotation: Class<*>): Builder = super.addAnnotation(annotation)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: KClass<*>): Builder = super.addAnnotation(annotation)

@Suppress("RedundantOverride")
override fun addKdoc(format: String, vararg args: Any): Builder = super.addKdoc(format, *args)

@Suppress("RedundantOverride")
override fun addKdoc(block: CodeBlock): Builder = super.addKdoc(block)
//endregion

public fun build(): FunSpec {
check(typeVariables.isEmpty() || !name.isAccessor) { "$name cannot have type variables" }
check(!(name == GETTER && parameters.isNotEmpty())) { "$name cannot have parameters" }
Expand Down
28 changes: 26 additions & 2 deletions kotlinpoet/src/main/java/com/squareup/kotlinpoet/ParameterSpec.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,10 @@ public class ParameterSpec private constructor(
) : Taggable.Builder<Builder>, Annotatable.Builder<Builder>, Documentable.Builder<Builder> {
internal var defaultValue: CodeBlock? = null

override val kdoc: CodeBlock.Builder = CodeBlock.builder()
override val annotations: MutableList<AnnotationSpec> = mutableListOf()
public val modifiers: MutableList<KModifier> = mutableListOf()
override val kdoc: CodeBlock.Builder = CodeBlock.builder()
override val tags: MutableMap<KClass<*>, Any> = mutableMapOf()
override val annotations: MutableList<AnnotationSpec> = mutableListOf()

public fun addModifiers(vararg modifiers: KModifier): Builder = apply {
this.modifiers += modifiers
Expand All @@ -128,6 +128,30 @@ public class ParameterSpec private constructor(
this.defaultValue = codeBlock
}

//region Overrides for binary compatibility
@Suppress("RedundantOverride")
override fun addAnnotations(annotationSpecs: Iterable<AnnotationSpec>): Builder =
super.addAnnotations(annotationSpecs)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: ClassName): Builder = super.addAnnotation(annotation)

@DelicateKotlinPoetApi(
message = "Java reflection APIs don't give complete information on Kotlin types. Consider " +
"using the kotlinpoet-metadata APIs instead.",
)
override fun addAnnotation(annotation: Class<*>): Builder = super.addAnnotation(annotation)

@Suppress("RedundantOverride")
override fun addAnnotation(annotation: KClass<*>): Builder = super.addAnnotation(annotation)

@Suppress("RedundantOverride")
override fun addKdoc(format: String, vararg args: Any): Builder = super.addKdoc(format, *args)

@Suppress("RedundantOverride")
override fun addKdoc(block: CodeBlock): Builder = super.addKdoc(block)
//endregion

public fun build(): ParameterSpec = ParameterSpec(this)
}

Expand Down

0 comments on commit 8b2c0fb

Please sign in to comment.