cleanup

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorAttribute.cs

@@ -2,8 +2,10 @@ namespace HotChocolate.Types;
 
 /// <summary>
 /// The <see cref="ErrorAttribute"/> registers a middleware that will catch all exceptions of
-/// type <see cref="ErrorAttribute.ErrorType"/>. By annotating the attribute the response type
-/// of the annotated resolver, will be automatically extended by a field of type
+/// type <see cref="ErrorAttribute.ErrorType"/> on mutations.
+///
+/// By annotating the attribute the response type
+/// of the annotated mutation resolver, will be automatically extended by a field of type
 /// <c>errors:[Error!]</c>. This field will return errors that are caught by the middleware.
 /// All the other fields on this type will be rewritten to nullable types. In case of a error
 /// these fields will be set to null.
@@ -184,9 +186,170 @@ public override void OnConfigure(
         => descriptor.Error(ErrorType);
 }
 
-public class ErrorAttribute<TError> : ErrorAttribute
+/// <summary>
+/// The <see cref="ErrorAttribute{T}"/> registers a middleware that will catch all exceptions of
+/// type <see cref="ErrorAttribute{T}.ErrorType"/> on mutations.
+///
+/// By annotating the attribute the response type
+/// of the annotated mutation resolver, will be automatically extended by a field of type
+/// <c>errors:[Error!]</c>. This field will return errors that are caught by the middleware.
+/// All the other fields on this type will be rewritten to nullable types. In case of a error
+/// these fields will be set to null.
+/// <para>
+/// There are three different ways to map exceptions to GraphQL errors.
+/// </para>
+/// </summary>
+/// <remarks>
+/// The idea of the error middleware is to keep the resolver clean of any error handling code
+/// and use exceptions to signal a error state. The HotChocolate schema is automatically
+/// rewritten into a common error handling pattern.
+/// <a href="https://xuorig.medium.com/a-guide-to-graphql-errors-bb9ba9f15f85">Learn More</a>
+/// </remarks>
+/// <example>
+/// <para>
+/// There are three different ways to map exceptions to GraphQL errors.
+/// </para>
+/// <list type="number">
+/// <item>
+/// <para>
+/// <b>Catching exceptions directly</b>
+/// </para>
+/// If <see cref="ErrorAttribute.ErrorType"/> is a exception, the exception is automatically
+/// mapped into a GraphQL error and the middleware will catch this exception
+/// <code>
+/// public class Mutation
+/// {
+///     [Error<SomeSpecificDomainError>]
+///     [Error<SomeOtherError>]
+///     public CreateUserPayload CreateUser(CreateUserInput input)
+///     {
+///        // ...
+///     }
+/// }
+///
+/// public record CreateUserInput(string UserName);
+///
+/// public record CreateUserPayload(User User);
+/// </code>
+/// This will generate the following schema
+/// <code>
+/// type Mutation {
+///   createUser(input: CreateUserInput!): CreateUserPayload!
+/// }
+///
+/// input CreateUserInput {
+///   userName: String!
+/// }
+///
+/// type CreateUserPayload {
+///   user: User
+///   errors: [CreateUserError!]
+/// }
+///
+/// type User {
+///   username: String
+/// }
+///
+/// interface Error {
+///   message: String!
+/// }
+///
+/// type SomeSpecificDomainError implements Error {
+///   message: String!
+/// }
+///
+/// type SomeOtherDomainError implements Error {
+///   message: String!
+/// }
+///
+/// union CreateUserError = SomeSpecificDomainError | SomeOtherDomainError
+/// </code>
+///    </item>
+/// <item>
+/// <para>
+/// <b>Map Exceptions with a factory method</b>
+/// </para>
+/// <para>
+/// If there should be any translation between exception and error, you can defined a class
+/// with factory methods. These factory methods receive a <see cref="Exception"/> and return
+/// a object which will be used as the representation of the error
+/// </para>
+/// <para>
+/// A factory method has to be `public static` and the name of the method has to be
+/// `CreateErrorFrom`. There should only be one parameter of type <see cref="Exception"/> and
+/// it can return a arbitrary class/struct/record that will be used as the representation
+/// of the error.
+/// </para>
+/// <code>
+/// public class MyCustomError
+/// {
+///     public static MyCustomError CreateErrorFrom(DomainExceptionA ex)
+///     {
+///         return new MyCustomError();
+///     }
+///
+///     public static MyCustomError CreateErrorFrom(DomainExceptionB ex)
+///     {
+///         return new MyCustomError();
+///     }
+///
+///     public string Message => "My custom error Message";
+/// }
+///
+/// public class Mutation
+/// {
+///     [Error<MyCustomError>]
+///     public CreateUserPayload CreateUser(CreateUserInput input)
+///     {
+///        // ...
+///     }
+/// }
+///
+/// public record CreateUserInput(string UserName);
+///
+/// public record CreateUserPayload(User User);
+/// </code>
+/// </item>
+/// <item>
+/// <para>
+/// <b>Map exceptions with a constructors</b>
+/// </para>
+/// <para>
+/// As a alternative to mapping exceptions with factory methods, you can also map the exception
+/// in the constructor of the object that should be used to represent the error in the schema.
+/// </para>
+/// <code>
+/// public class MyCustomError
+/// {
+///     public MyCustomError(MyCustomDomainException exception)
+///     {
+///         Message = exception.Message;
+///     }
+///
+///     public MyCustomError(MyCustomDomainException2 exception)
+///     {
+///         Message = exception.Message;
+///     }
+///
+///     public string Message { get; }
+/// }
+///
+/// public class Mutation
+/// {
+///     [Error<MyCustomError>]
+///     public CreateUserPayload CreateUser(CreateUserInput input)
+///     {
+///        // ...
+///     }
+/// }
+/// </code>
+/// </item>
+/// </list>
+/// </example>
+public sealed class ErrorAttribute<TError> : ErrorAttribute
 {
+    /// <inheritdoc cref="ErrorAttribute"/>
     public ErrorAttribute() : base(typeof(TError))
     {
     }
-}
+}

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorContextDataExtensions.cs

@@ -10,6 +10,6 @@ public static ExtensionData MarkAsError(this ExtensionData extensionData)
         return extensionData;
     }
 
-    public static bool IsError(this ExtensionData extensionData) =>
-        extensionData.ContainsKey(IsErrorType);
+    public static bool IsError(this ExtensionData extensionData)
+        => extensionData.ContainsKey(IsErrorType);
 }

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorDefinition.cs

@@ -1,6 +1,6 @@
 namespace HotChocolate.Types;
 
-internal class ErrorDefinition
+internal sealed class ErrorDefinition
 {
     public ErrorDefinition(Type runtimeType, Type schemaType, CreateError factory)
     {

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorInterfaceType.cs

@@ -1,6 +1,6 @@
 namespace HotChocolate.Types;
 
-internal class ErrorInterfaceType : InterfaceType
+internal sealed class ErrorInterfaceType : InterfaceType
 {
     protected override void Configure(IInterfaceTypeDescriptor descriptor)
     {

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorMiddleware.cs

@@ -2,8 +2,6 @@ namespace HotChocolate.Types;
 
 internal sealed class ErrorMiddleware
 {
-    public const string MiddlewareIdentifier = "HotChocolate.Types.Errors.ErrorMiddleware";
-
     public static readonly object ErrorObject = new();
 
     private readonly FieldDelegate _next;

src/HotChocolate/Core/src/Types.Mutations/Errors/ErrorObjectType.cs

@@ -4,7 +4,7 @@
 
 namespace HotChocolate.Types;
 
-internal class ErrorObjectType<T> : ObjectType<T>
+internal sealed class ErrorObjectType<T> : ObjectType<T>
 {
     protected override void Configure(IObjectTypeDescriptor<T> descriptor)
     {

src/HotChocolate/Core/src/Types.Mutations/Errors/ExceptionObjectType.cs

@@ -1,6 +1,6 @@
 namespace HotChocolate.Types;
 
-internal class ExceptionObjectType<T> : ObjectType<T> where T : Exception
+internal sealed class ExceptionObjectType<T> : ObjectType<T> where T : Exception
 {
     protected override void Configure(IObjectTypeDescriptor<T> descriptor)
     {
@@ -21,7 +21,7 @@ private static string GetNameFromException()
     {
         var name = typeof(T).Name;
         const string exceptionSuffix = nameof(Exception);
-        
+
         if (name.EndsWith(exceptionSuffix))
         {
             return $"{name.Substring(0, name.Length - exceptionSuffix.Length)}Error";

src/HotChocolate/Core/src/Types.Mutations/Extensions/ErrorObjectFieldDescriptorExtensions.cs

@@ -8,7 +8,9 @@ public static class ErrorObjectFieldDescriptorExtensions
 {
     /// <summary>
     /// The <c>.Error&lt;TError>()</c> extension method registers a middleware that will catch
-    /// all exceptions of type <typeparamref name="TError"/>. By annotating the attribute the
+    /// all exceptions of type <typeparamref name="TError"/> on mutations.
+    ///
+    /// By applying the error extension to a mutation field the
     /// response type of the annotated resolver, will be automatically extended by a field of
     /// type <c>errors:[Error!]</c>. This field will return errors that are caught by the
     /// middleware. All the other fields on this type will be rewritten to nullable types.
@@ -178,8 +180,10 @@ public static IObjectFieldDescriptor Error<TError>(this IObjectFieldDescriptor d
         Error(descriptor, typeof(TError));
 
     /// <summary>
-    /// The <c>.Error()</c> extension method registers a middleware that will catch all
-    /// exceptions of type <paramref name="errorType"/>. By annotating the attribute the
+    /// The <c>.Error&lt;TError>()</c> extension method registers a middleware that will catch
+    /// all exceptions of type <typeparamref name="TError"/> on mutations.
+    ///
+    /// By applying the error extension to a mutation field the
     /// response type of the annotated resolver, will be automatically extended by a field of
     /// type <c>errors:[Error!]</c>. This field will return errors that are caught by the
     /// middleware. All the other fields on this type will be rewritten to nullable types.

src/HotChocolate/Core/src/Types.Mutations/Extensions/ErrorSchemaBuilderExtensions.cs

@@ -22,8 +22,8 @@ public static class ErrorSchemaBuilderExtensions
     /// <returns>j
     /// The schema builder
     /// </returns>
-    public static ISchemaBuilder AddErrorInterfaceType<T>(this ISchemaBuilder schemaBuilder) =>
-        schemaBuilder.AddErrorInterfaceType(typeof(T));
+    public static ISchemaBuilder AddErrorInterfaceType<T>(this ISchemaBuilder schemaBuilder)
+        => schemaBuilder.AddErrorInterfaceType(typeof(T));
 
     /// <summary>
     /// Defines the common interface that all errors implement.
@@ -44,6 +44,6 @@ public static ISchemaBuilder AddErrorInterfaceType<T>(this ISchemaBuilder schema
     /// </returns>
     public static ISchemaBuilder AddErrorInterfaceType(
         this ISchemaBuilder schemaBuilder,
-        Type type) =>
-        schemaBuilder.SetContextData(ErrorContextDataKeys.ErrorType, type);
+        Type type)
+        => schemaBuilder.SetContextData(ErrorContextDataKeys.ErrorType, type);
 }