Include error documentation and result documentation into the GraphQL…

… description. (#1524, #1516)

Co-authored-by: Moritz Brandes <mb@grannyandsmith.com>
Co-authored-by: Michael Staib <michael@chillicream.com>

src/HotChocolate/Core/src/Types/Types/Descriptors/Conventions/DefaultNamingConventions.cs

@@ -51,7 +51,7 @@ public virtual string GetArgumentDescription(ParameterInfo parameter)
             var description = parameter.GetGraphQLDescription();
             if (string.IsNullOrWhiteSpace(description))
             {
-                description = _documentation.GetSummary(parameter);
+                description = _documentation.GetDescription(parameter);
             }
 
             return description;
@@ -86,7 +86,7 @@ public virtual string GetEnumValueDescription(object value)
                     string description = enumMember.GetGraphQLDescription();
                     if (string.IsNullOrEmpty(description))
                     {
-                        return _documentation.GetSummary(enumMember);
+                        return _documentation.GetDescription(enumMember);
                     }
                     return description;
                 }
@@ -119,7 +119,7 @@ public virtual string GetEnumValueDescription(object value)
             var description = member.GetGraphQLDescription();
             if (string.IsNullOrWhiteSpace(description))
             {
-                description = _documentation.GetSummary(member);
+                description = _documentation.GetDescription(member);
             }
 
             return description;
@@ -163,7 +163,7 @@ public virtual string GetTypeDescription(Type type, TypeKind kind)
             var description = type.GetGraphQLDescription();
             if (string.IsNullOrWhiteSpace(description))
             {
-                description = _documentation.GetSummary(type);
+                description = _documentation.GetDescription(type);
             }
 
             return description;

src/HotChocolate/Core/src/Types/Types/Descriptors/Conventions/IDocumentationProvider.cs

@@ -1,12 +1,54 @@
 using System;
 using System.Reflection;
 
+#nullable enable
+
 namespace HotChocolate.Types.Descriptors
 {
+    /// <summary>
+    /// The documentation provider is able to extract GraphQL type system
+    /// documentation from the associated .NET type system.
+    /// </summary>
     public interface IDocumentationProvider
     {
-        string GetSummary(Type type);
-        string GetSummary(MemberInfo member);
-        string GetSummary(ParameterInfo parameter);
+        /// <summary>
+        /// Gets the documentation for a GraphQL type from the
+        /// associated <see cref="Type" />.
+        /// </summary>
+        /// <param name="type">
+        /// The type from which the documentation shall be extracted.
+        /// </param>
+        /// <returns>
+        /// Returns a markdown string (https://commonmark.org)
+        /// describing the GraphQL type.
+        /// </returns>
+        string? GetDescription(Type type);
+
+        /// <summary>
+        /// Gets the documentation for a GraphQL input-, output-field or
+        /// directive argument from the associated <see cref="MemberInfo" />.
+        /// </summary>
+        /// <param name="member">
+        /// The member from which the documentation shall be extracted.
+        /// </param>
+        /// <returns>
+        /// Returns a markdown string (https://commonmark.org)
+        /// describing the GraphQL input-, output-field or
+        /// directive argument,
+        /// </returns>
+        string? GetDescription(MemberInfo member);
+
+        /// <summary>
+        /// Gets the documentation for a GraphQL field argument from the
+        /// associated <see cref="ParameterInfo" />.
+        /// </summary>
+        /// <param name="parameter">
+        /// The parameter from which the documentation shall be extracted.
+        /// </param>
+        /// <returns>
+        /// Returns a markdown string (https://commonmark.org)
+        /// describing the GraphQL field argument.
+        /// </returns>
+        string? GetDescription(ParameterInfo parameter);
     }
 }

src/HotChocolate/Core/src/Types/Types/Descriptors/Conventions/NoopDocumentationProvider.cs

@@ -0,0 +1,17 @@
+using System;
+using System.Reflection;
+
+#nullable enable
+
+namespace HotChocolate.Types.Descriptors
+{
+    internal sealed class NoopDocumentationProvider
+        : IDocumentationProvider
+    {
+        public string? GetDescription(Type type) => null;
+
+        public string? GetDescription(MemberInfo member) => null;
+
+        public string? GetDescription(ParameterInfo parameter) => null;
+    }
+}