From c350a4c2e948b24d90acbc1ad192709d1b0d0ab2 Mon Sep 17 00:00:00 2001
From: Paul Daniels <paulpdaniels@gmail.com>
Date: Sat, 6 Nov 2021 18:20:23 +0800
Subject: [PATCH] address comment feedback

---
 core/src/main/scala/caliban/GraphQL.scala          | 7 +++++++
 core/src/main/scala/caliban/GraphQLAspect.scala    | 5 +++++
 core/src/main/scala/caliban/wrappers/Wrapper.scala | 8 ++++----
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/core/src/main/scala/caliban/GraphQL.scala b/core/src/main/scala/caliban/GraphQL.scala
index 37658284f..c8416e88a 100644
--- a/core/src/main/scala/caliban/GraphQL.scala
+++ b/core/src/main/scala/caliban/GraphQL.scala
@@ -142,6 +142,13 @@ trait GraphQL[-R] { self =>
       override val additionalDirectives: List[__Directive] = self.additionalDirectives
     }
 
+  /**
+   * Attaches an aspect that will wrap the entire GraphQL so that it can be manipulated.
+   * This method is a higher-level abstraction of [[withWrapper]] which allows the caller to
+   * completely replace or change all aspects of the schema.
+   * @param aspect A wrapper type that will be applied to this GraphQL
+   * @return A new GraphQL API
+   */
   final def @@[LowerR <: UpperR, UpperR <: R](aspect: GraphQLAspect[LowerR, UpperR]): GraphQL[UpperR] =
     aspect(self)
 
diff --git a/core/src/main/scala/caliban/GraphQLAspect.scala b/core/src/main/scala/caliban/GraphQLAspect.scala
index c8c551425..f46023859 100644
--- a/core/src/main/scala/caliban/GraphQLAspect.scala
+++ b/core/src/main/scala/caliban/GraphQLAspect.scala
@@ -1,5 +1,10 @@
 package caliban
 
+/**
+ * A `GraphQLAspect` is wrapping type similar to a polymorphic function, which is capable
+ * of transforming a GraphQL into another while possibly enlarging the required environment type.
+ * It allows a flexible way to augment an existing GraphQL with new capabilities or features.
+ */
 trait GraphQLAspect[+LowerR, -UpperR] { self =>
   def apply[R >: LowerR <: UpperR](gql: GraphQL[R]): GraphQL[R]
 
diff --git a/core/src/main/scala/caliban/wrappers/Wrapper.scala b/core/src/main/scala/caliban/wrappers/Wrapper.scala
index aa1a59885..ed2383757 100644
--- a/core/src/main/scala/caliban/wrappers/Wrapper.scala
+++ b/core/src/main/scala/caliban/wrappers/Wrapper.scala
@@ -1,15 +1,15 @@
 package caliban.wrappers
 
-import scala.annotation.tailrec
 import caliban.CalibanError.{ ExecutionError, ParsingError, ValidationError }
 import caliban.execution.{ ExecutionRequest, FieldInfo }
 import caliban.introspection.adt.__Introspection
 import caliban.parsing.adt.Document
 import caliban.wrappers.Wrapper.CombinedWrapper
-import caliban.{ CalibanError, GraphQLRequest, GraphQLResponse, ResponseValue }
-import zio.{ UIO, ZIO }
+import caliban._
 import zio.query.ZQuery
-import caliban.{ GraphQL, GraphQLAspect }
+import zio.{ UIO, ZIO }
+
+import scala.annotation.tailrec
 
 /**
  * A `Wrapper[-R]` represents an extra layer of computation that can be applied on top of Caliban's query handling.