address comment feedback

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)
 

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]
 

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.