Add documentation for Builder and fix build for BIT_SET_FLAGS

kordlib · Aug 21, 2023 · ce16284 · ce16284
1 parent 091d630
commit ce16284
Show file tree

Hide file tree

Showing 12 changed files with 219 additions and 52 deletions.
diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt
@@ -430,22 +430,38 @@ public class ActivityFlags internal constructor(
     public class Builder(
         private var `value`: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [ActivityFlag].
+         */
         public operator fun ActivityFlag.unaryPlus() {
             this@Builder.value = this@Builder.value or this.value
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [ActivityFlags].
+         */
         public operator fun ActivityFlags.unaryPlus() {
             this@Builder.value = this@Builder.value or this.value
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ActivityFlag].
+         */
         public operator fun ActivityFlag.unaryMinus() {
             this@Builder.value = this@Builder.value and this.value.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ActivityFlags].
+         */
         public operator fun ActivityFlags.unaryMinus() {
             this@Builder.value = this@Builder.value and this.value.inv()
         }
 
+        /**
+         * Returns an instance of [ActivityFlags] that has all bits set that are currently set in
+         * this [Builder].
+         */
         public fun build(): ActivityFlags = ActivityFlags(value)
 
         /**

diff --git a/.../build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt b/.../build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt
@@ -508,22 +508,38 @@ public class ApplicationFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [ApplicationFlag].
+         */
         public operator fun ApplicationFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [ApplicationFlags].
+         */
         public operator fun ApplicationFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ApplicationFlag].
+         */
         public operator fun ApplicationFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ApplicationFlags].
+         */
         public operator fun ApplicationFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [ApplicationFlags] that has all bits set that are currently set in
+         * this [Builder].
+         */
         public fun build(): ApplicationFlags = ApplicationFlags(code)
 
         /**

diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt
@@ -360,22 +360,38 @@ public class ChannelFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [ChannelFlag].
+         */
         public operator fun ChannelFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [ChannelFlags].
+         */
         public operator fun ChannelFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ChannelFlag].
+         */
         public operator fun ChannelFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [ChannelFlags].
+         */
         public operator fun ChannelFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [ChannelFlags] that has all bits set that are currently set in
+         * this [Builder].
+         */
         public fun build(): ChannelFlags = ChannelFlags(code)
 
         /**

diff --git a/.../build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt b/.../build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt
@@ -388,22 +388,38 @@ public class GuildMemberFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [GuildMemberFlag].
+         */
         public operator fun GuildMemberFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [GuildMemberFlags].
+         */
         public operator fun GuildMemberFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [GuildMemberFlag].
+         */
         public operator fun GuildMemberFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [GuildMemberFlags].
+         */
         public operator fun GuildMemberFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [GuildMemberFlags] that has all bits set that are currently set in
+         * this [Builder].
+         */
         public fun build(): GuildMemberFlags = GuildMemberFlags(code)
 
         /**

diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt
@@ -503,22 +503,38 @@ public class MessageFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [MessageFlag].
+         */
         public operator fun MessageFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [MessageFlags].
+         */
         public operator fun MessageFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [MessageFlag].
+         */
         public operator fun MessageFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [MessageFlags].
+         */
         public operator fun MessageFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [MessageFlags] that has all bits set that are currently set in
+         * this [Builder].
+         */
         public fun build(): MessageFlags = MessageFlags(code)
 
         /**

diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt
@@ -561,23 +561,39 @@ public class Permissions internal constructor(
     public class Builder(
         private val code: DiscordBitSet = EmptyBitSet(),
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [Permission].
+         */
         public operator fun Permission.unaryPlus() {
             this@Builder.code.add(this.code)
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [Permissions].
+         */
         public operator fun Permissions.unaryPlus() {
             this@Builder.code.add(this.code)
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [Permission].
+         */
         public operator fun Permission.unaryMinus() {
             this@Builder.code.remove(this.code)
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [Permissions].
+         */
         public operator fun Permissions.unaryMinus() {
             this@Builder.code.remove(this.code)
         }
 
-        public fun build(): Permissions = Permissions(code)
+        /**
+         * Returns an instance of [Permissions] that has all bits set that are currently set in this
+         * [Builder].
+         */
+        public fun build(): Permissions = Permissions(code.copy())
 
         /**
          * @suppress

diff --git a/...uild/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt b/...uild/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt
@@ -426,22 +426,38 @@ public class SystemChannelFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [SystemChannelFlag].
+         */
         public operator fun SystemChannelFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [SystemChannelFlags].
+         */
         public operator fun SystemChannelFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [SystemChannelFlag].
+         */
         public operator fun SystemChannelFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [SystemChannelFlags].
+         */
         public operator fun SystemChannelFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [SystemChannelFlags] that has all bits set that are currently set
+         * in this [Builder].
+         */
         public fun build(): SystemChannelFlags = SystemChannelFlags(code)
 
         /**

diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt
@@ -575,22 +575,38 @@ public class UserFlags internal constructor(
     public class Builder(
         private var code: Int = 0,
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [UserFlag].
+         */
         public operator fun UserFlag.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [UserFlags].
+         */
         public operator fun UserFlags.unaryPlus() {
             this@Builder.code = this@Builder.code or this.code
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [UserFlag].
+         */
         public operator fun UserFlag.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [UserFlags].
+         */
         public operator fun UserFlags.unaryMinus() {
             this@Builder.code = this@Builder.code and this.code.inv()
         }
 
+        /**
+         * Returns an instance of [UserFlags] that has all bits set that are currently set in this
+         * [Builder].
+         */
         public fun build(): UserFlags = UserFlags(code)
 
         /**

diff --git a/common/src/commonTest/kotlin/entity/PermissionTest.kt b/common/src/commonTest/kotlin/entity/PermissionTest.kt
@@ -37,4 +37,16 @@ class PermissionTest {
         assertNotEquals(a, c)
         assertNotEquals(b, c)
     }
+
+    @Test
+    fun modifying_Builder_after_build_does_not_affect_built_instances() {
+        val builder = Permissions.Builder()
+        val a = builder.build()
+        builder.apply { +Permission.Administrator }
+        val b = builder.build()
+        val c = builder.build()
+        assertNotEquals(a, b)
+        assertNotEquals(a, c)
+        assertEquals(b, c)
+    }
 }
diff --git a/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt b/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt
@@ -449,23 +449,39 @@ public class Intents internal constructor(
     public class Builder(
         private val code: DiscordBitSet = EmptyBitSet(),
     ) {
+        /**
+         * Sets all bits in the [Builder] that are set in this [Intent].
+         */
         public operator fun Intent.unaryPlus() {
             this@Builder.code.add(this.code)
         }
 
+        /**
+         * Sets all bits in the [Builder] that are set in this [Intents].
+         */
         public operator fun Intents.unaryPlus() {
             this@Builder.code.add(this.code)
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [Intent].
+         */
         public operator fun Intent.unaryMinus() {
             this@Builder.code.remove(this.code)
         }
 
+        /**
+         * Unsets all bits in the [Builder] that are set in this [Intents].
+         */
         public operator fun Intents.unaryMinus() {
             this@Builder.code.remove(this.code)
         }
 
-        public fun build(): Intents = Intents(code)
+        /**
+         * Returns an instance of [Intents] that has all bits set that are currently set in this
+         * [Builder].
+         */
+        public fun build(): Intents = Intents(code.copy())
 
         /**
          * @suppress