Introduce Modifiable interface to standardize modifiers API

docs/changelog.md

@@ -8,6 +8,7 @@ Change Log
 * Fix: Preserve nullability in `KSType.toClassName()`. (#1956)
 * New: Add `KSTypeAlias.toClassName()`. (#1956)
 * New: Add `KSType.toClassNameOrNull()`. (#1956)
+* New: Introduce `Modifiable` interface to standardize `KModifier` API across specs. (#2005)
 
 ## Version 1.18.1
 

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/FunSpec.kt

@@ -42,13 +42,14 @@ public class FunSpec private constructor(
   OriginatingElementsHolder by delegateOriginatingElementsHolder,
   ContextReceivable by contextReceivers,
   Annotatable,
-  Documentable {
+  Documentable,
+  Modifiable {
   public val name: String = builder.name
   override val kdoc: CodeBlock = builder.kdoc.build()
   public val returnKdoc: CodeBlock = builder.returnKdoc
   public val receiverKdoc: CodeBlock = builder.receiverKdoc
   override val annotations: List<AnnotationSpec> = builder.annotations.toImmutableList()
-  public val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
+  override val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
   public val typeVariables: List<TypeVariableName> = builder.typeVariables.toImmutableList()
   public val receiverType: TypeName? = builder.receiverType
 
@@ -307,7 +308,8 @@ public class FunSpec private constructor(
     OriginatingElementsHolder.Builder<Builder>,
     ContextReceivable.Builder<Builder>,
     Annotatable.Builder<Builder>,
-    Documentable.Builder<Builder> {
+    Documentable.Builder<Builder>,
+    Modifiable.Builder<Builder> {
     internal var returnKdoc = CodeBlock.EMPTY
     internal var receiverKdoc = CodeBlock.EMPTY
     internal var receiverType: TypeName? = null
@@ -317,7 +319,7 @@ public class FunSpec private constructor(
     internal val body = CodeBlock.builder()
     override val kdoc: CodeBlock.Builder = CodeBlock.builder()
     override val annotations: MutableList<AnnotationSpec> = mutableListOf()
-    public val modifiers: MutableList<KModifier> = mutableListOf()
+    override val modifiers: MutableSet<KModifier> = mutableSetOf()
     public val typeVariables: MutableList<TypeVariableName> = mutableListOf()
     public val parameters: MutableList<ParameterSpec> = mutableListOf()
     override val tags: MutableMap<KClass<*>, Any> = mutableMapOf()
@@ -326,14 +328,6 @@ public class FunSpec private constructor(
     @ExperimentalKotlinPoetApi
     override val contextReceiverTypes: MutableList<TypeName> = mutableListOf()
 
-    public fun addModifiers(vararg modifiers: KModifier): Builder = apply {
-      this.modifiers += modifiers
-    }
-
-    public fun addModifiers(modifiers: Iterable<KModifier>): Builder = apply {
-      this.modifiers += modifiers
-    }
-
     public fun jvmModifiers(modifiers: Iterable<Modifier>) {
       var visibility = KModifier.INTERNAL
       for (modifier in modifiers) {

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/Modifiable.kt

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2024 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.squareup.kotlinpoet
+
+/** A spec that has a set of [KModifier]s attached to it. */
+public interface Modifiable {
+  public val modifiers: Set<KModifier>
+
+  public interface Builder<out T : Builder<T>> {
+    public val modifiers: MutableSet<KModifier>
+
+    /**
+     * Add one or multiple modifiers to this spec.
+     *
+     * Note that not all [KModifier]s can be applied to a specific spec, and specs may or may not
+     * validate modifiers at runtime. Consult Kotlin documentation on which modifiers are allowed on
+     * specific Kotlin constructs.
+     */
+    @Suppress("UNCHECKED_CAST")
+    public fun addModifiers(vararg modifiers: KModifier): T = apply {
+      this.modifiers += modifiers
+    } as T
+
+    /**
+     * Add a collection of modifiers to this spec.
+     *
+     * Note that not all [KModifier]s can be applied to a specific spec, and specs may or may not
+     * validate modifiers at runtime. Consult Kotlin documentation on which modifiers are allowed on
+     * specific Kotlin constructs.
+     */
+    @Suppress("UNCHECKED_CAST")
+    public fun addModifiers(modifiers: Iterable<KModifier>): T = apply {
+      this.modifiers += modifiers
+    } as T
+  }
+}

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/ParameterSpec.kt

@@ -29,11 +29,11 @@ import kotlin.reflect.KClass
 public class ParameterSpec private constructor(
   builder: Builder,
   private val tagMap: TagMap = builder.buildTagMap(),
-) : Taggable by tagMap, Annotatable, Documentable {
+) : Taggable by tagMap, Annotatable, Documentable, Modifiable {
   public val name: String = builder.name
   override val kdoc: CodeBlock = builder.kdoc.build()
   override val annotations: List<AnnotationSpec> = builder.annotations.toImmutableList()
-  public val modifiers: Set<KModifier> = builder.modifiers
+  override val modifiers: Set<KModifier> = builder.modifiers
     .also {
       LinkedHashSet(it).apply {
         removeAll(ALLOWED_PARAMETER_MODIFIERS)
@@ -94,22 +94,17 @@ public class ParameterSpec private constructor(
   public class Builder internal constructor(
     internal val name: String,
     internal val type: TypeName,
-  ) : Taggable.Builder<Builder>, Annotatable.Builder<Builder>, Documentable.Builder<Builder> {
+  ) : Taggable.Builder<Builder>,
+    Annotatable.Builder<Builder>,
+    Documentable.Builder<Builder>,
+    Modifiable.Builder<Builder> {
     internal var defaultValue: CodeBlock? = null
 
-    public val modifiers: MutableList<KModifier> = mutableListOf()
+    override val modifiers: MutableSet<KModifier> = mutableSetOf()
     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
-    }
-
-    public fun addModifiers(modifiers: Iterable<KModifier>): Builder = apply {
-      this.modifiers += modifiers
-    }
-
     @Deprecated(
       "There are no jvm modifiers applicable to parameters in Kotlin",
       ReplaceWith(""),

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/PropertySpec.kt

@@ -34,13 +34,14 @@ public class PropertySpec private constructor(
   OriginatingElementsHolder by delegateOriginatingElementsHolder,
   ContextReceivable by contextReceivers,
   Annotatable,
-  Documentable {
+  Documentable,
+  Modifiable {
   public val mutable: Boolean = builder.mutable
   public val name: String = builder.name
   public val type: TypeName = builder.type
   override val kdoc: CodeBlock = builder.kdoc.build()
   override val annotations: List<AnnotationSpec> = builder.annotations.toImmutableList()
-  public val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
+  override val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
   public val typeVariables: List<TypeVariableName> = builder.typeVariables.toImmutableList()
   public val initializer: CodeBlock? = builder.initializer
   public val delegated: Boolean = builder.delegated
@@ -176,7 +177,8 @@ public class PropertySpec private constructor(
     OriginatingElementsHolder.Builder<Builder>,
     ContextReceivable.Builder<Builder>,
     Annotatable.Builder<Builder>,
-    Documentable.Builder<Builder> {
+    Documentable.Builder<Builder>,
+    Modifiable.Builder<Builder> {
     internal var isPrimaryConstructorParameter = false
     internal var mutable = false
     internal var initializer: CodeBlock? = null
@@ -185,7 +187,7 @@ public class PropertySpec private constructor(
     internal var setter: FunSpec? = null
     internal var receiverType: TypeName? = null
 
-    public val modifiers: MutableList<KModifier> = mutableListOf()
+    override val modifiers: MutableSet<KModifier> = mutableSetOf()
     public val typeVariables: MutableList<TypeVariableName> = mutableListOf()
     override val tags: MutableMap<KClass<*>, Any> = mutableMapOf()
     override val kdoc: CodeBlock.Builder = CodeBlock.builder()
@@ -200,14 +202,6 @@ public class PropertySpec private constructor(
       this.mutable = mutable
     }
 
-    public fun addModifiers(vararg modifiers: KModifier): Builder = apply {
-      this.modifiers += modifiers
-    }
-
-    public fun addModifiers(modifiers: Iterable<KModifier>): Builder = apply {
-      this.modifiers += modifiers
-    }
-
     public fun addTypeVariables(typeVariables: Iterable<TypeVariableName>): Builder = apply {
       this.typeVariables += typeVariables
     }

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/TypeAliasSpec.kt

@@ -26,10 +26,10 @@ import kotlin.reflect.KClass
 public class TypeAliasSpec private constructor(
   builder: Builder,
   private val tagMap: TagMap = builder.buildTagMap(),
-) : Taggable by tagMap, Annotatable, Documentable {
+) : Taggable by tagMap, Annotatable, Documentable, Modifiable {
   public val name: String = builder.name
   public val type: TypeName = builder.type
-  public val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
+  override val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
   public val typeVariables: List<TypeVariableName> = builder.typeVariables.toImmutableList()
   override val kdoc: CodeBlock = builder.kdoc.build()
   override val annotations: List<AnnotationSpec> = builder.annotations.toImmutableList()
@@ -69,25 +69,16 @@ public class TypeAliasSpec private constructor(
   public class Builder internal constructor(
     internal val name: String,
     internal val type: TypeName,
-  ) : Taggable.Builder<Builder>, Annotatable.Builder<Builder>, Documentable.Builder<Builder> {
-    public val modifiers: MutableSet<KModifier> = mutableSetOf()
+  ) : Taggable.Builder<Builder>,
+    Annotatable.Builder<Builder>,
+    Documentable.Builder<Builder>,
+    Modifiable.Builder<Builder> {
+    override val modifiers: MutableSet<KModifier> = mutableSetOf()
     public val typeVariables: MutableSet<TypeVariableName> = mutableSetOf()
     override val tags: MutableMap<KClass<*>, Any> = mutableMapOf()
     override val kdoc: CodeBlock.Builder = CodeBlock.builder()
     override val annotations: MutableList<AnnotationSpec> = mutableListOf()
 
-    public fun addModifiers(vararg modifiers: KModifier): Builder = apply {
-      modifiers.forEach(this::addModifier)
-    }
-
-    public fun addModifiers(modifiers: Iterable<KModifier>): Builder = apply {
-      modifiers.forEach(this::addModifier)
-    }
-
-    private fun addModifier(modifier: KModifier) {
-      this.modifiers.add(modifier)
-    }
-
     public fun addTypeVariables(typeVariables: Iterable<TypeVariableName>): Builder = apply {
       this.typeVariables += typeVariables
     }

kotlinpoet/src/jvmMain/kotlin/com/squareup/kotlinpoet/TypeSpec.kt

@@ -48,13 +48,14 @@ public class TypeSpec private constructor(
   ContextReceivable by contextReceivers,
   Annotatable,
   Documentable,
+  Modifiable,
   TypeSpecHolder,
   MemberSpecHolder {
   public val kind: Kind = builder.kind
   public val name: String? = builder.name
   override val kdoc: CodeBlock = builder.kdoc.build()
   override val annotations: List<AnnotationSpec> = builder.annotations.toImmutableList()
-  public val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
+  override val modifiers: Set<KModifier> = builder.modifiers.toImmutableSet()
   public val typeVariables: List<TypeVariableName> = builder.typeVariables.toImmutableList()
   public val primaryConstructor: FunSpec? = builder.primaryConstructor
   public val superclass: TypeName = builder.superclass
@@ -476,6 +477,7 @@ public class TypeSpec private constructor(
     ContextReceivable.Builder<Builder>,
     Annotatable.Builder<Builder>,
     Documentable.Builder<Builder>,
+    Modifiable.Builder<Builder>,
     TypeSpecHolder.Builder<Builder>,
     MemberSpecHolder.Builder<Builder> {
     internal var primaryConstructor: FunSpec? = null
@@ -499,7 +501,7 @@ public class TypeSpec private constructor(
 
     @ExperimentalKotlinPoetApi
     override val contextReceiverTypes: MutableList<TypeName> = mutableListOf()
-    public val modifiers: MutableSet<KModifier> = mutableSetOf(*modifiers)
+    override val modifiers: MutableSet<KModifier> = mutableSetOf(*modifiers)
     public val superinterfaces: MutableMap<TypeName, CodeBlock?> = mutableMapOf()
     public val enumConstants: MutableMap<String, TypeSpec> = mutableMapOf()
     public val typeVariables: MutableList<TypeVariableName> = mutableListOf()
@@ -511,14 +513,14 @@ public class TypeSpec private constructor(
     @Deprecated("Use annotations property", ReplaceWith("annotations"), ERROR)
     public val annotationSpecs: MutableList<AnnotationSpec> get() = annotations
 
-    public fun addModifiers(vararg modifiers: KModifier): Builder = apply {
+    override fun addModifiers(vararg modifiers: KModifier): Builder {
       check(!isAnonymousClass) { "forbidden on anonymous types." }
-      this.modifiers += modifiers
+      return super.addModifiers(*modifiers)
     }
 
-    public fun addModifiers(modifiers: Iterable<KModifier>): Builder = apply {
+    override fun addModifiers(modifiers: Iterable<KModifier>): Builder {
       check(!isAnonymousClass) { "forbidden on anonymous types." }
-      this.modifiers += modifiers
+      return super.addModifiers(modifiers)
     }
 
     public fun addTypeVariables(typeVariables: Iterable<TypeVariableName>): Builder = apply {