Clean up docs (#759)

* Clean up docs

* Update extended scalars docs

* Update exception docs

Co-authored-by: Shane Myrick <[email protected]>

Author: smyrick

docs/blogs-and-videos.md

@@ -5,24 +5,22 @@ title: Blogs & Videos
 
 Here are some links to other blog posts and videos which may provide further examples and reading.
 
-### From the Expedia Group team
-
-#### graphql-kotlin
+## graphql-kotlin
 Articles and videos specifically about `graphql-kotlin`
 
-* 📝 [graphql-kotlin: Generate a GraphQL schema from Kotlin code](https://medium.com/expedia-group-tech/graphql-kotlin-generate-a-graphql-schema-from-kotlin-code-21d1dc2f6e27)
-* 📝 [Release of graphql-kotlin 1.0.0!](https://medium.com/expedia-group-tech/release-of-graphql-kotlin-1-0-0-791ad85d3116)
-* 📝 [Creating GraphQL Schemas in Kotlin](https://medium.com/expedia-group-tech/creating-graphql-schemas-in-kotlin-aaaac0ab0672)
-* 📝 [Apollo Federation in a GraphQL Kotlin Server](https://medium.com/expedia-group-tech/apollo-federation-in-a-graphql-kotlin-server-115cea51607a)
-* 📝 [Creating a Reactive GraphQL Server with Spring Boot and Kotlin](https://medium.com/expedia-group-tech/creating-a-reactive-graphql-server-with-spring-boot-and-kotlin-54aca7316470)
-* 📺 [Bootiful GraphQL with Kotlin (Dariusz Kuc, Guillaume Scheibel)](https://www.youtube.com/watch?v=7YJyPXjLdug&index=25) (en)
-* 📝 [🎉 Announcing graphql-kotlin 2.0!](https://medium.com/expedia-group-tech/graphql-kotlin-2-0-4006ea41f774)
-* 📝 [Introducing GraphQL Kotlin Client](https://medium.com/expedia-group-tech/introducing-graphql-kotlin-client-b32dc3061a6f)
+* 📝  [graphql-kotlin: Generate a GraphQL schema from Kotlin code](https://medium.com/expedia-group-tech/graphql-kotlin-generate-a-graphql-schema-from-kotlin-code-21d1dc2f6e27)
+* 📝  [Release of graphql-kotlin 1.0.0!](https://medium.com/expedia-group-tech/release-of-graphql-kotlin-1-0-0-791ad85d3116)
+* 📝  [Creating GraphQL Schemas in Kotlin](https://medium.com/expedia-group-tech/creating-graphql-schemas-in-kotlin-aaaac0ab0672)
+* 📝  [Apollo Federation in a GraphQL Kotlin Server](https://medium.com/expedia-group-tech/apollo-federation-in-a-graphql-kotlin-server-115cea51607a)
+* 📝  [Creating a Reactive GraphQL Server with Spring Boot and Kotlin](https://medium.com/expedia-group-tech/creating-a-reactive-graphql-server-with-spring-boot-and-kotlin-54aca7316470)
+* 📺  [Bootiful GraphQL with Kotlin (Dariusz Kuc, Guillaume Scheibel)](https://www.youtube.com/watch?v=7YJyPXjLdug&index=25) (en)
+* 📝  [Announcing graphql-kotlin 2.0!](https://medium.com/expedia-group-tech/graphql-kotlin-2-0-4006ea41f774)
+* 📝  [Introducing GraphQL Kotlin Client](https://medium.com/expedia-group-tech/introducing-graphql-kotlin-client-b32dc3061a6f)
 
-#### GraphQL
+## GraphQL
 Articles and videos about how Expedia Group is using GraphQL
 
-* 📺 [Creating a federated schema for a global company (Shane Myrick)](https://youtu.be/MuD3TAP0D9Y) (en)
-* 📺 [Migrer ses APIs vers GraphQL: pourquoi? comment! (Guillaume Scheibel)](https://youtu.be/IRIkpvJo95s) (fr)
-* 📺 [Migrate your APIs to GraphQL: how? and why! (Guillaume Scheibel)](https://youtu.be/IkPMpzQ-TRI) (en)
-* 📺 [Transforming customer experiences and your organization with GraphQL (Jim Gust, Dan Boerner)](https://youtu.be/Jt-ZD4zj4Ow) (en)
+* 📺  [Creating a federated schema for a global company (Shane Myrick)](https://youtu.be/MuD3TAP0D9Y) (en)
+* 📺  [Migrer ses APIs vers GraphQL: pourquoi? comment! (Guillaume Scheibel)](https://youtu.be/IRIkpvJo95s) (fr)
+* 📺  [Migrate your APIs to GraphQL: how? and why! (Guillaume Scheibel)](https://youtu.be/IkPMpzQ-TRI) (en)
+* 📺  [Transforming customer experiences and your organization with GraphQL (Jim Gust, Dan Boerner)](https://youtu.be/Jt-ZD4zj4Ow) (en)

docs/getting-started.md

@@ -54,11 +54,11 @@ compile(group: 'com.expediagroup', name: 'graphql-kotlin-spring-server', version
 
 ## Generating a Schema
 
-While we have included a server implementation, you can use `graphql-kotlin-schema-generator` to generate a schema from Kotlin code and expose it with any server library.
+You can use `graphql-kotlin-schema-generator` to generate a schema from Kotlin code and expose it with any server library.
 
 See the docs in [Schema Generator Getting Started](./schema-generator/schema-generator-getting-started.md).
 
-### Federation
+### Apollo Federation
 
 Using `graphql-kotlin-federation`, you can generate an [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/federation-spec/) complaint schema.
 
@@ -73,3 +73,13 @@ See the docs in [Spring Server Overview](./spring-server/spring-overview.md).
 `graphql-kotlin-plugins` can be used to generate a `graphql-kotlin-client` from an existing schema that is easy to use and type-safe.
 
 See the docs in [Client Overview](./client/client-overview.md).
+
+## Examples
+
+The `examples` module is a collection of working code and examples on how to use all of the `graphql-kotlin` modules.
+
+See the [example docs](./examples.md) for more info.
+
+## Blogs and Videos
+
+You can find more posts and recorded conference talks on GraphQL and `graphql-kotlin` on our [Blogs and Videos](./blogs-and-videos.md) page.

docs/schema-generator/customizing-schemas/deprecating-schema.md

@@ -3,40 +3,31 @@ id: deprecating-schema
 title: Deprecating Schema
 ---
 
-### Deprecating Fields
-
 GraphQL schemas can have fields marked as deprecated. Instead of creating a custom annotation,
 `graphql-kotlin-schema-generator` just looks for the `kotlin.Deprecated` annotation and will use that annotation message
 for the deprecated reason.
 
 ```kotlin
 class SimpleQuery {
   @Deprecated(message = "this query is deprecated", replaceWith = ReplaceWith("shinyNewQuery"))
-  @GraphQLDescription("old query that should not be used always returns false")
   fun simpleDeprecatedQuery(): Boolean = false
 
-  @GraphQLDescription("new query that always returns true")
   fun shinyNewQuery(): Boolean = true
 }
 ```
 
 The above query would produce the following GraphQL schema:
 
 ```graphql
-schema {
-  query: Query
-}
-
 type Query {
-
-  """old query that should not be used always returns false"""
   simpleDeprecatedQuery: Boolean! @deprecated(reason: "this query is deprecated, replace with shinyNewQuery")
 
-  """new query that always returns true"""
   shinyNewQuery: Boolean!
 }
 ```
 
 While you can deprecate any fields/functions/classes in your Kotlin code, GraphQL only supports deprecation directive on
 the fields (which correspond to Kotlin fields and functions) and enum values.
 
+Deprecation of input types is not yet supported [in the GraphQL spec](https://github.com/graphql/graphql-spec/pull/525).
+

docs/schema-generator/customizing-schemas/documenting-fields.md

@@ -4,7 +4,7 @@ title: Documenting Schema
 ---
 
 Since Javadocs are not available at runtime for introspection, `graphql-kotlin-schema-generator` includes an annotation
-class `@GraphQLDescription` that can be used to add schema descriptions to *any* GraphQL schema element. The string value can be in the Markdown format, however due to an [issue in graphql-java](https://github.com/graphql-java/graphql-java/issues/1677) the `#` character is not supported to mark header levels.
+class `@GraphQLDescription` that can be used to add schema descriptions to *any* GraphQL schema element. The string value can be in the Markdown format.
 
 ```kotlin
 @GraphQLDescription("A useful widget")
@@ -13,9 +13,8 @@ data class Widget(
   val value: Int?
 )
 
-class WidgetQuery: Query {
-
-  @GraphQLDescription("creates new widget for given ID")
+class WidgetQuery {
+  @GraphQLDescription("Creates new widget for given ID")
   fun widgetById(@GraphQLDescription("The special ingredient") id: Int): Widget? = Widget(id)
 }
 ```
@@ -28,7 +27,7 @@ schema {
 }
 
 type Query {
-  """creates new widget for given ID"""
+  """Creates new widget for given ID"""
   widgetById(
     """The special ingredient"""
     id: Int!

docs/schema-generator/customizing-schemas/excluding-fields.md

@@ -22,10 +22,6 @@ class SimpleQuery {
 The above query would produce the following GraphQL schema:
 
 ```graphql
-schema {
-  query: Query
-}
-
 type Query {
   doSomething(value: Int!): Boolean!
 }

docs/schema-generator/customizing-schemas/renaming-fields.md

@@ -21,7 +21,7 @@ type MyCustomName {
 }
 ```
 
-### Known Issues
+## Known Issues
 > NOTE: Due to how we deserialize input classes, if you rename a field of an input class you must also annotate the field with the Jackson annotation @JsonProperty. See [issue 493](https://github.com/ExpediaGroup/graphql-kotlin/issues/493) for more info.
 
 ```kotlin

docs/schema-generator/execution/async-models.md

@@ -29,11 +29,6 @@ class Query {
 will produce the following schema
 
 ```graphql
-
-schema {
-  query: Query
-}
-
 type Query {
   getUser(id: String!): User
 }

docs/schema-generator/execution/exceptions.md

@@ -3,22 +3,34 @@ id: exceptions
 title: Exceptions and Partial Data
 ---
 
-Exceptions thrown during execution of a query will result in a GraphQLError that is added to a list of errors of the result. See
-[graphql-java documentation](https://www.graphql-java.com/documentation/v14/execution/) for more details on how to customize your exception handling.
+## Returning GraphQL Errors
 
-### Partial Data
+Exceptions thrown during execution of an operation will result in an empty data response and a GraphQLError that is added to a list of errors of the result.
+See [graphql-java documentation](https://www.graphql-java.com/documentation/v14/execution/) for more details on how to customize your exception handling.
 
-GraphQL allows you to return both data and errors in a single response. Depending on the criticality of the encountered error you may want to return
-partial data together with the corresponding errors. In Kotlin, functions return only a single value, which means that in order to return both data
+
+```kotlin
+fun getRandomNumberOrError(): Int {
+    val num = Random().nextInt(100)
+    return if (num <= 50) num else throw Exception("number is greater than 50")
+}
+```
+
+## Returning Data and Errors
+
+GraphQL allows you to return both data and errors in a single response, as long as the data returned still matches the schema. Depending on the criticality of the encountered error, instead of throwing an exception, you may want to return
+default data or use a nullable field, but still include more information in the `errors` block. In Kotlin, functions return only a single value, which means that in order to return both data
 and errors you have to explicitly return them wrapped in a `DataFetcherResult` object.
 
 ```kotlin
 class DataAndErrorsQuery {
-  fun returnDataAndErrors(): DataFetcherResult<String> {
-    // some logic here to populate data and capture error
-    return DataFetcherResult.newResult<String>()
-      .data(myData)
-      .error(myError)
+  fun returnDataAndErrors(): DataFetcherResult<String?> {
+    val data: String? = getData()
+    val error = if (data == null) MyError() else null
+
+    return DataFetcherResult.newResult<String?>()
+      .data(data)
+      .error(error)
       .build()
   }
 }

docs/schema-generator/writing-schemas/arguments.md

@@ -7,21 +7,15 @@ Method arguments are automatically exposed as part of the arguments to the corre
 
 ```kotlin
 class SimpleQuery{
-
-  @GraphQLDescription("performs some operation")
-  fun doSomething(@GraphQLDescription("super important value") value: Int): Boolean = true
+  fun doSomething(value: Int): Boolean = true
 }
 ```
 
 The above Kotlin code will generate following GraphQL schema:
 
 ```graphql
 type Query {
-  """performs some operation"""
-  doSomething(
-    """super important value"""
-    value: Int!
-  ): Boolean!
+  doSomething(value: Int!): Boolean!
 }
 ```
 
@@ -38,22 +32,15 @@ For example, the following code:
 
 ```kotlin
 class WidgetMutation {
-
-    @GraphQLDescription("modifies passed in widget so it doesn't have null value")
-    fun processWidget(@GraphQLDescription("widget to be modified") widget: Widget): Widget {
+    fun processWidget(widget: Widget): Widget {
         if (null == widget.value) {
             widget.value = 42
         }
         return widget
     }
 }
 
-@GraphQLDescription("A useful widget")
-data class Widget(
-    @GraphQLDescription("The widget's value that can be null")
-    var value: Int? = nul
-) {
-    @GraphQLDescription("returns original value multiplied by target OR null if original value was null")
+data class Widget(var value: Int? = nul) {
     fun multiplyValueBy(multiplier: Int) = value?.times(multiplier)
 }
 ```
@@ -62,32 +49,17 @@ Will generate the following schema:
 
 ```graphql
 type Mutation {
-  """modifies passed in widget so it doesn't have null value"""
-  processWidget(
-    """widget to be modified"""
-    widget: WidgetInput!
-  ): Widget!
+  processWidget(widget: WidgetInput!): Widget!
 }
 
-"""A useful widget"""
 type Widget {
-
-  """The widget's value that can be null"""
   value: Int
-
-  """
-  returns original value multiplied by target OR null if original value was null
-  """
   multiplyValueBy(multiplier: Int!): Int
 }
 
-"""A useful widget"""
 input WidgetInput {
-
-  """The widget's value that can be null"""
   value: Int
 }
-
 ```
 
 Please note that only fields are exposed in the input objects. Functions will only be available on the GraphQL output
@@ -104,11 +76,7 @@ defaults (even if they are marked as nullable). Therefore in order for a GraphQL
 nullable and also specify a default Kotlin value.
 
 ```kotlin
-    @GraphQLDescription("query with optional input")
-    fun doSomethingWithOptionalInput(
-            @GraphQLDescription("this field is required") requiredValue: Int,
-            @GraphQLDescription("this field is optional") optionalValue: Int?)
-            = "required value=$requiredValue, optional value=$optionalValue"
+fun doSomethingWithOptionalInput(requiredValue: Int, optionalValue: Int?) = "required value=$requiredValue, optional value=$optionalValue"
 ```
 
 NOTE: Non nullable input fields will always require users to specify the value regardless of whether a default Kotlin value