Fix empty elements in documentation comments

.editorconfig

@@ -313,6 +313,8 @@ dotnet_diagnostic.RCS1205.severity = warning
 dotnet_diagnostic.RCS1214.severity = warning
 # Convert interpolated string to concatenation.
 dotnet_diagnostic.RCS1217.severity = warning
+# Unused element in a documentation comment.
+dotnet_diagnostic.RCS1228.severity = warning
 # Unnecessary null-forgiving operator.
 dotnet_diagnostic.RCS1249.severity = warning
 # Remove unnecessary braces.

src/GreenDonut/src/GreenDonut.Abstractions/Attributes/DataLoaderModuleAttribute.cs

@@ -21,7 +21,6 @@ public DataLoaderModuleAttribute(string name)
     /// <summary>
     /// Gets the module name.
     /// </summary>
-    /// <value></value>
     public string Name { get; }
 
     /// <summary>

src/GreenDonut/src/GreenDonut.Abstractions/IPromise.cs

@@ -23,13 +23,13 @@ public interface IPromise
     /// <summary>
     /// Tries to set the result of the async work for this promise.
     /// </summary>
-    /// <param name="result"></param>
+    /// <param name="result">The result of the async work.</param>
     void TrySetResult(object? result);
 
     /// <summary>
     /// Tries to set an exception for the async work for this promise.
     /// </summary>
-    /// <param name="exception"></param>
+    /// <param name="exception">The exception to set.</param>
     void TrySetError(Exception exception);
 
     /// <summary>

src/GreenDonut/src/GreenDonut.Abstractions/Promise.cs

@@ -6,7 +6,7 @@ namespace GreenDonut;
 /// a <see cref="Task{TResult}"/>,
 /// or a <see cref="TaskCompletionSource{TResult}"/>.
 /// </summary>
-/// <typeparam name="TValue"></typeparam>
+/// <typeparam name="TValue">The type of the value that the promise will produce.</typeparam>
 public readonly struct Promise<TValue> : IPromise
 {
     private readonly TaskCompletionSource<TValue>? _completionSource;

src/GreenDonut/src/GreenDonut.Data.EntityFramework/Extensions/PagingQueryableExtensions.cs

@@ -295,7 +295,9 @@ public static async ValueTask<Page<T>> ToPageAsync<T>(
     /// <typeparam name="TValue">
     /// The type of the items in the queryable.
     /// </typeparam>
-    /// <returns></returns>
+    /// <returns>
+    /// A dictionary mapping each parent key to its page of results.
+    /// </returns>
     /// <exception cref="ArgumentException">
     /// If the queryable does not have any keys specified.
     /// </exception>
@@ -337,7 +339,9 @@ public static ValueTask<Dictionary<TKey, Page<TValue>>> ToBatchPageAsync<TKey, T
     /// <typeparam name="TValue">
     /// The type of the items in the queryable.
     /// </typeparam>
-    /// <returns></returns>
+    /// <returns>
+    /// A dictionary mapping each parent key to its page of results.
+    /// </returns>
     /// <exception cref="ArgumentException">
     /// If the queryable does not have any keys specified.
     /// </exception>
@@ -383,7 +387,9 @@ public static ValueTask<Dictionary<TKey, Page<TValue>>> ToBatchPageAsync<TKey, T
     /// <typeparam name="TElement">
     /// The type of the source elements from which keys and values are projected.
     /// </typeparam>
-    /// <returns></returns>
+    /// <returns>
+    /// A dictionary mapping each parent key to its page of results.
+    /// </returns>
     /// <exception cref="ArgumentException">
     /// If the queryable does not have any keys specified.
     /// </exception>
@@ -432,7 +438,9 @@ public static ValueTask<Dictionary<TKey, Page<TValue>>> ToBatchPageAsync<TKey, T
     /// <typeparam name="TElement">
     /// The type of the source elements from which keys and values are projected.
     /// </typeparam>
-    /// <returns></returns>
+    /// <returns>
+    /// A dictionary mapping each parent key to its page of results.
+    /// </returns>
     /// <exception cref="ArgumentException">
     /// If the queryable does not have any keys specified.
     /// </exception>

src/GreenDonut/src/GreenDonut.Data/Cursors/CursorKey.cs

@@ -44,7 +44,7 @@ public sealed class CursorKey(
     /// <param name="cursorValue">
     /// The span within the overall cursor that represents the key value.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The parsed key value.</returns>
     public object? Parse(ReadOnlySpan<byte> cursorValue)
         => CursorKeySerializerHelper.Parse(cursorValue, serializer);
 

src/GreenDonut/src/GreenDonut/PromiseCacheObserver.cs

@@ -96,8 +96,8 @@ public virtual void Accept(IPromiseCache cache, string? skipCacheKeyType)
     /// <summary>
     /// The method is called when a new task is added to the cache.
     /// </summary>
-    /// <param name="cache"></param>
-    /// <param name="promise"></param>
+    /// <param name="cache">The promise cache that the new entry was added to.</param>
+    /// <param name="promise">The promise that was added to the cache.</param>
     public abstract void OnNext(IPromiseCache cache, Promise<TValue> promise);
 
     public void Dispose()

src/GreenDonut/test/GreenDonut.Data.EntityFramework.Tests/TestContext/Product.cs

@@ -52,7 +52,9 @@ public class Product
     /// In this case, it is the responsibility of the client to determine if the amount that is returned is the same as quantityDesired.
     /// It is invalid to pass in a negative number.
     /// </summary>
-    /// <param name="quantityDesired"></param>
+    /// <param name="quantityDesired">
+    /// The desired number of units to remove from stock.
+    /// </param>
     /// <returns>int: Returns the number actually removed from stock. </returns>
     ///
     public int RemoveStock(int quantityDesired)
@@ -76,7 +78,9 @@ public int RemoveStock(int quantityDesired)
 
     /// <summary>
     /// Increments the quantity of a particular item in inventory.
-    /// <param name="quantity"></param>
+    /// <param name="quantity">
+    /// The number of units to add to stock.
+    /// </param>
     /// <returns>int: Returns the quantity that has been added to stock</returns>
     /// </summary>
     public int AddStock(int quantity)

src/HotChocolate/ApolloFederation/src/ApolloFederation/Representation.cs

@@ -28,7 +28,6 @@ public Representation(string typeName, ObjectValueNode data)
     /// <summary>
     /// Gets the type name of the entity.
     /// </summary>
-    /// <value></value>
     public string TypeName { get; }
 
     /// <summary>

src/HotChocolate/ApolloFederation/src/ApolloFederation/Types/Directives/KeyDescriptorExtensions.cs

@@ -33,7 +33,7 @@ public static class KeyDescriptorExtensions
     /// <param name="resolvable">
     /// Boolean flag to indicate whether this entity is resolvable locally.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The entity resolver descriptor.</returns>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="descriptor"/> is <c>null</c>.
     /// </exception>
@@ -74,7 +74,7 @@ public static IEntityResolverDescriptor<IObjectTypeDescriptor> Key(
     /// <param name="resolvable">
     /// Boolean flag to indicate whether this entity is resolvable locally.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The entity resolver descriptor.</returns>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="descriptor"/> is <c>null</c>.
     /// </exception>
@@ -125,7 +125,7 @@ public static IEntityResolverDescriptor<T, IObjectTypeDescriptor> Key<T>(
     /// <param name="resolvable">
     /// Boolean flag to indicate whether this entity is resolvable locally.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The entity resolver descriptor.</returns>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="descriptor"/> is <c>null</c>.
     /// </exception>
@@ -166,7 +166,7 @@ public static IEntityResolverDescriptor<IInterfaceTypeDescriptor> Key(
     /// <param name="resolvable">
     /// Boolean flag to indicate whether this entity is resolvable locally.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The entity resolver descriptor.</returns>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="descriptor"/> is <c>null</c>.
     /// </exception>

src/HotChocolate/AspNetCore/src/AspNetCore.Authorization.Opa/IOpaService.cs

@@ -11,7 +11,7 @@ public interface IOpaService
     /// <param name="policyPath">The string parameter representing path of the evaluating policy.</param>
     /// <param name="request">The instance <see cref="OpaQueryRequest"/>.</param>
     /// <param name="ct">Cancellation token.</param>
-    /// <returns></returns>
+    /// <returns>The OPA policy decision response.</returns>
     Task<OpaQueryResponse> QueryAsync(
         string policyPath,
         OpaQueryRequest request,

src/HotChocolate/AspNetCore/src/AspNetCore/Extensions/HotChocolateAspNetCoreHostingBuilderExtensions.cs

@@ -24,7 +24,9 @@ public static class HotChocolateAspNetCoreHostingBuilderExtensions
     /// <param name="disableDefaultSecurity">
     /// Defines if the default security policy should be disabled.
     /// </param>
-    /// <returns></returns>
+    /// <returns>
+    /// The <see cref="IRequestExecutorBuilder"/> for configuration chaining.
+    /// </returns>
     public static IRequestExecutorBuilder AddGraphQL(
         this IHostApplicationBuilder builder,
         string? schemaName = null,

src/HotChocolate/AspNetCore/src/AspNetCore/Extensions/HotChocolateAspNetCoreServiceCollectionExtensions.Http.cs

@@ -84,7 +84,9 @@ public static IRequestExecutorBuilder AddHttpRequestInterceptor<T>(
     /// <param name="handler">
     /// A delegate that allows to configure the GraphQL request.
     /// </param>
-    /// <returns></returns>
+    /// <returns>
+    /// The <see cref="IRequestExecutorBuilder"/> for configuration chaining.
+    /// </returns>
     public static IRequestExecutorBuilder AddHttpRequestInterceptor(
         this IRequestExecutorBuilder builder,
         Func<HttpContext, IRequestExecutor, OperationRequestBuilder, CancellationToken, ValueTask> handler)

src/HotChocolate/AspNetCore/src/Transport.Abstractions/OperationBatchRequest.cs

@@ -173,7 +173,10 @@ public override int GetHashCode()
     /// <param name="right">
     /// The second <see cref="OperationBatchRequest"/> to compare.
     /// </param>
-    /// <returns></returns>
+    /// <returns>
+    /// <c>true</c> if the two objects are equal;
+    /// otherwise, <c>false</c>.
+    /// </returns>
     public static bool operator ==(OperationBatchRequest left, OperationBatchRequest right)
         => left.Equals(right);
 
@@ -186,7 +189,10 @@ public override int GetHashCode()
     /// <param name="right">
     /// The second <see cref="OperationBatchRequest"/> to compare.
     /// </param>
-    /// <returns></returns>
+    /// <returns>
+    /// <c>true</c> if the two objects are not equal;
+    /// otherwise, <c>false</c>.
+    /// </returns>
     public static bool operator !=(OperationBatchRequest left, OperationBatchRequest right)
         => !left.Equals(right);
 }

src/HotChocolate/AspNetCore/src/Transport.Http/DefaultGraphQLHttpClient.cs

@@ -76,7 +76,7 @@ public DefaultGraphQLHttpClient(HttpClient httpClient)
     /// <param name="cancellationToken">
     /// A cancellation token that can be used to cancel the HTTP request.
     /// </param>
-    /// <returns></returns>
+    /// <returns>The GraphQL HTTP response.</returns>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="request"/> is <see langword="null"/>.
     /// </exception>

src/HotChocolate/AspNetCore/src/Transport.Sockets/MessagePipeline.cs

@@ -55,8 +55,8 @@ public void OnCompleted<T>(Action<T> completed, T state) where T : class
     /// <summary>
     /// Run the pipeline and process messages.
     /// </summary>
-    /// <param name="cancellationToken"></param>
-    /// <returns></returns>
+    /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task RunAsync(CancellationToken cancellationToken)
     {
         await Task.WhenAll(

src/HotChocolate/Caching/src/Caching.Memory/Cache.cs

@@ -263,7 +263,7 @@ private CacheEntry InsertNew(string key, TValue value)
     /// <summary>
     /// Returns all keys in the cache. This method is for testing only.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>All keys currently in the cache.</returns>
     internal IEnumerable<string> GetKeys()
     {
         foreach (var entry in _ring)

src/HotChocolate/Core/src/Abstractions/IExecutable.cs

@@ -44,8 +44,8 @@ public interface IExecutable
     /// Returns the only element of a default value if no such element exists. This method
     /// throws an exception if more than one element satisfies the condition.
     /// </summary>
-    /// <param name="cancellationToken"></param>
-    /// <returns></returns>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the execution.</param>
+    /// <returns>Returns the result, or a default value if no such element exists.</returns>
     ValueTask<object?> SingleOrDefaultAsync(CancellationToken cancellationToken = default);
 
     /// <summary>

src/HotChocolate/Core/src/Abstractions/IQueryableExecutable.cs

@@ -3,7 +3,7 @@ namespace HotChocolate;
 /// <summary>
 /// Represents an executable that has a queryable as its source.
 /// </summary>
-/// <typeparam name="T"></typeparam>
+/// <typeparam name="T">The element type.</typeparam>
 public interface IQueryableExecutable<T> : IExecutable<T>
 {
     /// <summary>

src/HotChocolate/Core/src/Abstractions/ModuleAttribute.cs

@@ -25,7 +25,6 @@ public ModuleAttribute(string name, ModuleOptions options = ModuleOptions.Defaul
     /// <summary>
     /// Gets the module name.
     /// </summary>
-    /// <value></value>
     public string Name { get; }
 
     /// <summary>

src/HotChocolate/Core/src/Execution.Abstractions/Execution/IRequestExecutorManager.cs

@@ -8,6 +8,6 @@ public interface IRequestExecutorManager : IRequestExecutorProvider
     /// <summary>
     /// Evict the request executor and schema with the given name.
     /// </summary>
-    /// <param name="schemaName"></param>
+    /// <param name="schemaName">The name of the schema whose executor shall be evicted.</param>
     void EvictExecutor(string? schemaName = null);
 }

src/HotChocolate/Core/src/Execution.Abstractions/Execution/OperationDocumentSourceText.cs

@@ -5,7 +5,7 @@ namespace HotChocolate.Execution;
 /// <summary>
 /// Represents a GraphQL operation document source texts that needs parsing before it can be executed.
 /// </summary>
-/// <param name="sourceText"></param>
+/// <param name="sourceText">The GraphQL operation document source text.</param>
 public sealed class OperationDocumentSourceText(string sourceText) : IOperationDocument
 {
     /// <summary>

src/HotChocolate/Core/src/Execution.Abstractions/Execution/OperationRequestBuilder.cs

@@ -571,7 +571,9 @@ public IOperationRequest Build()
     /// <summary>
     /// Creates a new instance of <see cref="OperationRequestBuilder" />.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>
+    /// A new <see cref="OperationRequestBuilder"/>.
+    /// </returns>
     public static OperationRequestBuilder New() => new();
 
     /// <summary>
@@ -580,7 +582,10 @@ public IOperationRequest Build()
     /// <param name="request">
     /// The existing request from which the new builder is created.
     /// </param>
-    /// <returns></returns>
+    /// <returns>
+    /// A new <see cref="OperationRequestBuilder"/> initialized from
+    /// the request.
+    /// </returns>
     /// <exception cref="NotSupportedException">
     /// The request type is not supported.
     /// </exception>

src/HotChocolate/Core/src/Execution.Abstractions/IVariableValueCollection.cs

@@ -17,7 +17,7 @@ public interface IVariableValueCollection : IEnumerable<VariableValue>
     /// Gets a coerced variable value from the collection.
     /// </summary>
     /// <param name="name">The variable name.</param>
-    /// <returns></returns>
+    /// <returns>The coerced variable value.</returns>
     /// <exception cref="GraphQLException">
     /// A GraphQL execution error is thrown when the
     /// requested variable cannot be found or cannot

src/HotChocolate/Core/src/Features/IFeatureCollection.cs

@@ -27,7 +27,7 @@ public interface IFeatureCollection : IEnumerable<KeyValuePair<Type, object>>
     /// <summary>
     /// Gets or sets a given feature. Setting a null value removes the feature.
     /// </summary>
-    /// <param name="key"></param>
+    /// <param name="key">The type of the feature to get or set.</param>
     /// <returns>The requested feature, or null if it is not present.</returns>
     object? this[Type key] { get; set; }
 

src/HotChocolate/Core/src/Types.Abstractions/Types/ArgumentAssignment.cs

@@ -101,7 +101,9 @@ public ArgumentAssignment(string name, IValueNode value)
     /// <summary>
     /// Returns a string representation of the current argument assignment.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>
+    /// A string representation of this argument assignment.
+    /// </returns>
     public override string ToString()
         => ToSyntaxNode().ToString(indented: true);
 

src/HotChocolate/Core/src/Types.CursorPagination/ConnectionPageInfo.cs

@@ -9,10 +9,10 @@ public class ConnectionPageInfo : IPageInfo
     /// <summary>
     /// Initializes <see cref="ConnectionPageInfo" />.
     /// </summary>
-    /// <param name="hasNextPage"></param>
-    /// <param name="hasPreviousPage"></param>
-    /// <param name="startCursor"></param>
-    /// <param name="endCursor"></param>
+    /// <param name="hasNextPage">Indicates whether more items exist after the current page.</param>
+    /// <param name="hasPreviousPage">Indicates whether more items exist before the current page.</param>
+    /// <param name="startCursor">The cursor of the first item in the current page.</param>
+    /// <param name="endCursor">The cursor of the last item in the current page.</param>
     public ConnectionPageInfo(
         bool hasNextPage,
         bool hasPreviousPage,

src/HotChocolate/Core/src/Types.CursorPagination/CursorPaginationAlgorithm.cs

@@ -19,7 +19,7 @@ public abstract class CursorPaginationAlgorithm<TQuery, TEntity> where TQuery :
     /// </summary>
     /// <param name="query">The query builder.</param>
     /// <param name="arguments">The paging arguments.</param>
-    /// <param name="totalCount"></param>
+    /// <param name="totalCount">The total number of items in the data set, or <c>null</c> if unknown.</param>
     /// <returns>
     /// Returns the connection.
     /// </returns>

src/HotChocolate/Core/src/Types.CursorPagination/Edge.cs

@@ -6,7 +6,7 @@ namespace HotChocolate.Types.Pagination;
 /// <summary>
 /// Represents an edge in a connection.
 /// </summary>
-/// <typeparam name="T"></typeparam>
+/// <typeparam name="T">The type of the node.</typeparam>
 public class Edge<T> : IEdge<T>
 {
     private readonly Func<Edge<T>, string>? _resolveCursor;

src/HotChocolate/Core/src/Types.OffsetPagination/Extensions/OffsetPaginationResolverContextExtensions.cs

@@ -12,8 +12,10 @@ internal static class OffsetPaginationResolverContextExtensions
     /// </para>
     /// <para>This method checks if the total count is selected</para>
     /// </summary>
-    /// <param name="context"></param>
-    /// <returns></returns>
+    /// <param name="context">The resolver context to inspect.</param>
+    /// <returns>
+    /// <c>true</c> if the total count field is included in the selection set; otherwise, <c>false</c>.
+    /// </returns>
     public static bool IsTotalCountSelected(this IResolverContext context)
     {
         // TotalCount is one of the heaviest operations. It is only necessary to load totalCount