Merge branch 'refs/heads/main' into alpha

# Conflicts:
#	docs/docs/inheritance.md
#	test/unit/should_handle_reserved_kotlin_keywords/expected.kt
#	test/unit/should_handle_top_level_types_properly/expected.kt

Author: danadajian

docs/docs/inheritance.md

@@ -37,7 +37,6 @@ open class MyType {
 Source code:
 
 ```kotlin
-import com.expediagroup.graphql.generator.annotations.GraphQLIgnore
 import com.expediagroup.graphql.server.operations.Query
 import com.types.generated.MyType as MyTypeInterface
 import com.types.generated.Query as QueryInterface
@@ -46,7 +45,6 @@ class MyQuery : Query, QueryInterface() {
   override fun resolveMyType(): MyTypeInterface = MyType()
 }
 
-@GraphQLIgnore
 class MyType : MyTypeInterface() {
   override fun resolveMe(input: String): String = "Hello world!"
 }
@@ -55,11 +53,14 @@ class MyType : MyTypeInterface() {
 As you can see, the generated code is not part of the implementation. Rather, it becomes an interface to inherit from in your implementation.
 This enforces a type contract between the schema and your resolver code.
 
-## Top Level Types
+Note that GraphQL Kotlin will use the implementation classes to generate the schema, not the generated interfaces.
+This means that all `@GraphQLDescription` and `@Deprecated` annotations have to be added to implementation classes
+in order to be propagated to the resulting schema.
 
-When dealing with top-level types, such as `Query` or `Mutation`, you can inherit from the generated class directly. This is because the generated class is open by default.
+## Top Level Types
 
-Given the following executable schema:
+When dealing with top-level types, i.e. `Query` and `Mutation`, you can inherit from the corresponding generated class
+to enforce the type contract. This is fine as long as all of your resolvers are contained in the same Query or Mutation class.
 
 ```graphql
 type Query {
@@ -68,7 +69,17 @@ type Query {
 }
 ```
 
-You might want to separate the implementation into multiple classes like so:
+```kotlin
+import com.expediagroup.graphql.server.operations.Query
+import com.types.generated.Query as QueryInterface
+
+class MyQuery : Query, QueryInterface() {
+  override fun foo(): String = "Hello"
+  override fun bar(): String = "World"
+}
+```
+
+However, you might want to separate the implementation into multiple classes like so:
 
 ```kotlin
 import com.expediagroup.graphql.server.operations.Query
@@ -82,7 +93,7 @@ class BarQuery : Query {
 }
 ```
 
-However, if you try to inherit from the generated `Query` class, you will get an error during schema generation.
+If you try to inherit from the generated `Query` class, you will get an error during schema generation.
 
 ```kotlin
 import com.expediagroup.graphql.server.operations.Query
@@ -97,7 +108,7 @@ class BarQuery : Query, QueryInterface() {
 }
 ```
 
-This is because the generated `Query` class contains both `foo` and `bar` fields, which causes a conflict when inherited by multiple implementation classes.
+This is because the generated `Query` class contains both `foo` and `bar` fields, which creates a conflict when inherited by multiple implementation classes.
 
 Instead, you should inherit from the field-level generated `Query` classes like so:
 
@@ -114,3 +125,5 @@ class BarQuery : Query, BarQueryInterface() {
   override fun bar(): String = "World"
 }
 ```
+
+This way, schema generation can complete without conflict, and you can separate your implementation into multiple classes!