Generate kord enums with KSP #686

lukellmann · 2022-09-11T14:01:17Z

This PR adds KSP and KotlinPoet to the project and introduces an annotation to generate "kord enums" (classes like ChannelType). All these classes are now generated with this annotation.

We have a lot of sealed classes like ChannelType (representing this) that are very similar. They all have:

a single property that represents the value (the value discord actually uses)
a serializer
a set of object subtypes that represent all known values
an Unknown subclass that we use for values that aren't documented / added yet

I gave them the name "kord enums" because they are essentially enums with the ability to represent unknown cases.

Every time we add a new one of these classes (e.g. when discord adds a new feature), we have to write a lot of boilerplate to make the class similar to the existing ones. But it's easy to bring in slight variations which leads to inconsistent code over time.
Adding new subtypes to these classes can also be error-prone, since it requires adding the new type and also adding it in the serializer which can be easy to forget (see b75e33f).

This PR introduces a KSP processor to solve these problems. It allows us to define these classes via annotations which reduces boilerplate, keeps consistency across these classes and ensures a single point of truth for the value (we had the value in the subtype declaration and serializer before).

Another benefit is that when we want to change something about all these classes, we just have to adjust the processor.

In the future we might use KSP to also generate other boilerplate heavy parts of kord (flags, builders etc.).

This PR also

implements equals, hashCode and toString for every kord enum.
adds WebhookType.Application (was missing before).
replaces DiscordGuildApplicationCommandPermission.Type with ApplicationCommandPermissionType because of technical reasons (can't generate nested classes).
removes deprecation from EmbedType.
adds a new entries property in the companion object of every generated kord enum with type List<KordEnumType> that is a list of all known entries. The name is taken from Kotlin's upcoming Enum.entries.
fixes a bug that deleted public threads would produce UnknownChannelThreadDeleteEvent instead of TextChannelThreadDeleteEvent.

# Conflicts: # common/src/main/kotlin/entity/DiscordChannel.kt # core/src/main/kotlin/entity/channel/Channel.kt

# Conflicts: # build.gradle.kts # buildSrc/build.gradle.kts # buildSrc/src/main/kotlin/kord-module.gradle.kts # common/src/main/kotlin/entity/DiscordChannel.kt # common/src/main/kotlin/entity/DiscordMessage.kt # core/src/main/kotlin/gateway/handler/ThreadEventHandler.kt

# Conflicts: # common/src/main/kotlin/entity/DiscordChannel.kt

…resetType`, `AutoModerationRuleEventType` and `AutoModerationActionType`

…`ExplicitContentFilter`, `VerificationLevel`, `NsfwLevel` and `PremiumTier`

… `GuildScheduledEventStatus`

…d files

lukellmann · 2022-09-11T14:07:18Z

.gitignore

 out/
 dokka/
+
+**/build/*
+!**/build/generated/


Right now I included the generated files by removing them from the .gitignore. I'm not sure if this is the way we should do it, @DRSchlaubi had some other ideas before, what do you say?

lukellmann · 2022-09-11T19:39:38Z

common/api/common.api

+public final class dev/kord/common/entity/WebhookType$Application : dev/kord/common/entity/WebhookType {
+	public static final field INSTANCE Ldev/kord/common/entity/WebhookType$Application;


WebhookType.Application is the only truly new API added in this PR (other API dump changes are only additions of equals(), hashCode(), toString(), entries, companion objects and deprecation artifacts)

lukellmann · 2022-09-11T20:10:32Z

core/src/main/kotlin/entity/channel/Channel.kt

-            PrivateThread -> TextChannelThread(data, kord)
-            PublicGuildThread -> TextChannelThread(data, kord)
+            PrivateThread, PublicGuildThread -> TextChannelThread(data, kord)


this is just code deduplication

lukellmann · 2022-09-11T20:12:21Z

core/src/main/kotlin/gateway/handler/ThreadEventHandler.kt

-            is ChannelType.PrivateThread,
-            is ChannelType.GuildText -> TextChannelThreadDeleteEvent(channel, old as? TextChannelThread, shard, context?.get())
+            ChannelType.PrivateThread,
+            ChannelType.PublicGuildThread -> TextChannelThreadDeleteEvent(channel, old as? TextChannelThread, shard, context?.get())


This was a bug: PublicGuildThreads would result in an UnknownChannelThreadDeleteEvent instead of a TextChannelThreadDeleteEvent

lukellmann · 2022-09-11T20:16:46Z

ksp-annotations/src/main/kotlin/GenerateKordEnum.kt

+    // TODO remove eventually
+    /** For migration purposes. */
+    val valuesPropertyName: String = "",
+    /** For migration purposes. */
+    val valuesPropertyType: ValuesPropertyType = NONE,
+    /** For migration purposes. */
+    val deprecatedSerializerName: String = "",


these are only added to preserve binary compatibility and will be removed eventually after the corresponding deprecation cycle

# Conflicts: # common/src/main/kotlin/entity/DiscordGuild.kt

lukellmann · 2022-09-12T03:45:45Z

This is ready

HopeBaron · 2022-09-12T06:12:45Z

does this mean that all Add x code are now redundant?
I've not looked at the code yet tho

lukellmann · 2022-09-12T11:37:39Z

Add x code? What do you mean?

HopeBaron · 2022-09-14T05:57:36Z

Error codes from other PRs

lukellmann · 2022-09-14T09:47:03Z

Nope, I haven't touched JsonErrorCode here. And apart from that, we still have to add new values.

@serializable

This PR adds bit flag classes to the code generation in Kord (see #686 for the reasoning of generating boilerplate heavy parts of Kord). It also tries to unify the API shape of all existing bit flag classes by deprecating some existing declarations and replacing them with declarations that all bit flag classes have in common. They now have this general API shape: sealed class SomeFlag(val shift: Int) { val value: ValueType operator fun plus(flag: SomeFlag): SomeFlags operator fun plus(flags: SomeFlags): SomeFlags class Unknown : SomeFlag object Flag1 : SomeFlag object Flag2 : SomeFlag // ... companion object { val entries: List<SomeFlag> fun fromShift(shift: Int): SomeFlag } } @serializable class SomeFlags(val value: ValueType) { val values: Set<SomeFlag> operator fun contains(flag: SomeFlag): Boolean operator fun contains(flags: SomeFlags): Boolean operator fun plus(flag: SomeFlag): SomeFlags operator fun plus(flags: SomeFlags): SomeFlags operator fun minus(flag: SomeFlag): SomeFlags operator fun minus(flags: SomeFlags): SomeFlags fun copy(builder: Builder.() -> Unit): SomeFlags class Builder(value: ValueType = /* ... */) { operator fun SomeFlag.unaryPlus() operator fun SomeFlags.unaryPlus() operator fun SomeFlag.unaryMinus() operator fun SomeFlags.unaryMinus() fun build(): SomeFlags } } fun SomeFlags(builder: SomeFlags.Builder.() -> Unit): SomeFlags fun SomeFlags(vararg flags: SomeFlag): SomeFlags fun SomeFlags(vararg flags: SomeFlags): SomeFlags fun SomeFlags(flags: Iterable<SomeFlag>): SomeFlags fun SomeFlags(flags: Iterable<SomeFlags>): SomeFlags This means that flag classes are no longer enum classes. Binary compatibility was preserved as far as possible, but the fact that these classes now no longer have java.lang.Enum as their supertype is a binary incompatible change. This PR also * adds ActivityFlag.PartyPrivacyFriends, ActivityFlag.PartyPrivacyVoiceChannel and ActivityFlag.Embedded (these were missing before) * deprecates UserFlag.System (it was undocumented in 2021[1]) * renames Intent.GuildBans to Intent.GuildModeration (see https://github.com/discord/discord-api-docs/pull/5849/files#diff-c24665b017972d8f7c266214d30655ea5e105826ef212048f9460632dd61e3df) * fixes a bug where .copy{ /* ... */ } would also modify the original instance for bit flags based on DiscordBitSet * fixes some minus functions that would toggle instead of remove bits (this.value xor other.value -> this.value and other.value.inv()) [1] discord/discord-api-docs@9293f0d490ac6acf9d627e429e5a8131b303b528S --------- Co-authored-by: lukellmann <[email protected]>

lukellmann added 30 commits July 14, 2022 19:55

Add KSP processor for enum generation

f30f7c3

Add options to deprecate values property

c110a92

Generate MessageStickerType

35dd217

Generate ChannelType

1c768a0

Suppress errors for HIDDEN entries

eb2be55

Merge branch '0.8.x' into refactor/enum-generation

c9e845e

# Conflicts: # common/src/main/kotlin/entity/DiscordChannel.kt # core/src/main/kotlin/entity/channel/Channel.kt

Use annotation constructors, small other changes

4ef0576

Fix errors after merge

56360df

Include generated symbols in dokka output

f8b5155

Check ksp output into vcs

af13bbb

Rename kordJvmOptions() to applyKordKotlinOptions()

f6f9bb2

Hardcode deprecation level for values property

22c212c

Wrapper class for annotation arguments

3d5b2d8

Rollback renames

6e86162

Merge branch '0.8.x' into refactor/enum-generation

2271de2

# Conflicts: # common/src/main/kotlin/entity/DiscordChannel.kt

Generate AuditLogEvent

e1e741b

Generate AutoModerationRuleTriggerType, `AutoModerationRuleKeywordP…

da27677

…resetType`, `AutoModerationRuleEventType` and `AutoModerationActionType`

Generate OverwriteType and VideoQualityMode

5dfba4f

Generate ComponentType, ButtonStyle and TextInputStyle

c39aaff

Generate DiscordConnectionVisibility

b2ec643

Generate GuildFeature

780113e

Generate DefaultMessageNotificationLevel, ExplicitContentFilter, …

df417ed

…`ExplicitContentFilter`, `VerificationLevel`, `NsfwLevel` and `PremiumTier`

Generate GuildScheduledEventPrivacyLevel, ScheduledEntityType and…

ffe5efd

… `GuildScheduledEventStatus`

Generate IntegrationExpireBehavior

914f06f

Generate InviteTargetType

10ffc50

Add missing GuildFeature.Commerce

77d9ae2

Generate MessageType

c961a98

Generate MessageActivityType and AllowedMentionType

2a01023

Generate StageInstancePrivacyLevel

a5db3bd

lukellmann added 7 commits September 11, 2022 20:29

Remove comments

c15e526

Binary compatibility for old public serializers

4dd5635

New order for KotlinPoet DSL

4ea2a61

Add toString to all kord enums

a60166d

Put KordEnumProcessorProvider and KordEnumProcessor into same file

735c464

Suppress "SpellCheckingInspection" and "GrazieInspection" in generate…

bb7bf54

…d files

Add KDoc for entries and value

100e9be

lukellmann commented Sep 12, 2022

View reviewed changes

Generate EmbedType

1d7fb28

lukellmann mentioned this pull request Sep 12, 2022

Deprecate GuildFeature.Commerce #678

Merged

Merge branch '0.8.x' into refactor/enum-generation

e418baf

# Conflicts: # common/src/main/kotlin/entity/DiscordGuild.kt

lukellmann force-pushed the refactor/enum-generation branch from 48a3e0c to e418baf Compare September 12, 2022 03:37

lukellmann marked this pull request as ready for review September 12, 2022 03:45

lukellmann requested review from HopeBaron and DRSchlaubi September 12, 2022 03:45

lukellmann added 2 commits September 12, 2022 07:20

Update dokka config

56804bd

Remove double slash in dokka source links

4750273

lukellmann added 2 commits September 12, 2022 15:24

Merge branch '0.8.x' into refactor/enum-generation

6eb6f0e

SOURCE retention for @KotlinPoetDsl

48fe706

lukellmann mentioned this pull request Sep 13, 2022

Bump DeprecationLevels #688

Merged

HopeBaron merged commit 10d8fc8 into 0.8.x Sep 18, 2022

lukellmann deleted the refactor/enum-generation branch September 20, 2022 14:15

lukellmann mentioned this pull request Oct 11, 2022

Kord enum updates #698

Merged

lukellmann mentioned this pull request Aug 24, 2023

Generate bit flags #766

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate kord enums with KSP #686

Generate kord enums with KSP #686

lukellmann commented Sep 11, 2022 •

edited

Loading

lukellmann Sep 11, 2022

lukellmann Sep 11, 2022

lukellmann Sep 11, 2022

lukellmann Sep 11, 2022

lukellmann Sep 11, 2022

lukellmann commented Sep 12, 2022

HopeBaron commented Sep 12, 2022

lukellmann commented Sep 12, 2022

HopeBaron commented Sep 14, 2022

lukellmann commented Sep 14, 2022

		public final class dev/kord/common/entity/WebhookType$Application : dev/kord/common/entity/WebhookType {
		public static final field INSTANCE Ldev/kord/common/entity/WebhookType$Application;

Generate kord enums with KSP #686

Generate kord enums with KSP #686

Conversation

lukellmann commented Sep 11, 2022 • edited Loading

lukellmann Sep 11, 2022

Choose a reason for hiding this comment

lukellmann Sep 11, 2022

Choose a reason for hiding this comment

lukellmann Sep 11, 2022

Choose a reason for hiding this comment

lukellmann Sep 11, 2022

Choose a reason for hiding this comment

lukellmann Sep 11, 2022

Choose a reason for hiding this comment

lukellmann commented Sep 12, 2022

HopeBaron commented Sep 12, 2022

lukellmann commented Sep 12, 2022

HopeBaron commented Sep 14, 2022

lukellmann commented Sep 14, 2022

lukellmann commented Sep 11, 2022 •

edited

Loading