Document queries and scenes

util/Seeder/IQuery.cs

@@ -1,15 +1,60 @@
 namespace Bit.Seeder;
 
+/// <summary>
+/// Base interface for query operations in the seeding system. The base interface should not be used directly, rather use `IQuery&lt;TRequest, TResult&gt;`.
+/// </summary>
+/// <remarks>
+/// Queries are synchronous, read-only operations that retrieve data from the seeding context.
+/// Unlike scenes which create data, queries fetch existing data based on request parameters.
+/// They follow a type-safe pattern using generics to ensure proper request/response handling
+/// while maintaining a common non-generic interface for dynamic invocation.
+/// </remarks>
 public interface IQuery
 {
+    /// <summary>
+    /// Gets the type of request this query expects.
+    /// </summary>
+    /// <returns>The request type that this query can process.</returns>
     Type GetRequestType();
+
+    /// <summary>
+    /// Executes the query based on the provided request object.
+    /// </summary>
+    /// <param name="request">The request object containing parameters for the query operation.</param>
+    /// <returns>The query result data as an object.</returns>
     object Execute(object request);
 }
 
+/// <summary>
+/// Generic query interface for synchronous, read-only operations with specific request and result types.
+/// </summary>
+/// <typeparam name="TRequest">The type of request object this query accepts.</typeparam>
+/// <typeparam name="TResult">The type of data this query returns.</typeparam>
+/// <remarks>
+/// Use this interface when you need to retrieve existing data from the seeding context based on
+/// specific request parameters. Queries are synchronous and do not modify data - they only read
+/// and return information. The explicit interface implementations allow dynamic invocation while
+/// maintaining type safety in the implementation.
+/// </remarks>
 public interface IQuery<TRequest, TResult> : IQuery where TRequest : class where TResult : class
 {
+    /// <summary>
+    /// Executes the query based on the provided strongly-typed request and returns typed result data.
+    /// </summary>
+    /// <param name="request">The request object containing parameters for the query operation.</param>
+    /// <returns>The typed query result data.</returns>
     TResult Execute(TRequest request);
 
+    /// <summary>
+    /// Gets the request type for this query.
+    /// </summary>
+    /// <returns>The type of TRequest.</returns>
     Type IQuery.GetRequestType() => typeof(TRequest);
+
+    /// <summary>
+    /// Adapts the non-generic Execute to the strongly-typed version.
+    /// </summary>
+    /// <param name="request">The request object to cast and process.</param>
+    /// <returns>The typed result cast to object.</returns>
     object IQuery.Execute(object request) => Execute((TRequest)request);
 }