add xml doc comments for IExecute/Async, IStoredProc/Async

PetaPoco/IExecute.cs

@@ -1,19 +1,25 @@
-namespace PetaPoco
+namespace PetaPoco
 {
+    /// <summary>
+    /// Defines an interface for executing SQL commands and queries.
+    /// </summary>
+    /// <remarks>
+    /// This interface provides methods for executing SQL non-query commands and scalar queries. It supports SQL commands and queries represented as strings or as <see cref="Sql">Sql Builder</see> objects.
+    /// </remarks>
     public interface IExecute
     {
         /// <summary>
         /// Executes a non-query command.
         /// </summary>
         /// <param name="sql">The SQL statement to execute.</param>
-        /// <param name="args">Arguments to any embedded parameters in the SQL.</param>
+        /// <param name="args">Arguments to any embedded parameters in the SQL statement.</param>
         /// <returns>The number of rows affected.</returns>
         int Execute(string sql, params object[] args);
 
         /// <summary>
         /// Executes a non-query command.
         /// </summary>
-        /// <param name="sql">An SQL builder object representing the query and its arguments.</param>
+        /// <param name="sql">An Sql builder object representing the SQL statement and its arguments.</param>
         /// <returns>The number of rows affected.</returns>
         int Execute(Sql sql);
 
@@ -22,15 +28,15 @@ public interface IExecute
         /// </summary>
         /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
         /// <param name="sql">The SQL query to execute.</param>
-        /// <param name="args">Arguments to any embedded parameters in the SQL.</param>
+        /// <param name="args">Arguments to any embedded parameters in the SQL statement.</param>
         /// <returns>The scalar value cast to <typeparamref name="T"/>.</returns>
         T ExecuteScalar<T>(string sql, params object[] args);
 
         /// <summary>
         /// Executes the query and returns the first column of the first row in the result set.
         /// </summary>
         /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
-        /// <param name="sql">An SQL builder object representing the query and its arguments.</param>
+        /// <param name="sql">An Sql builder object representing the SQL query and its arguments.</param>
         /// <returns>The scalar value cast to <typeparamref name="T"/>.</returns>
         T ExecuteScalar<T>(Sql sql);
     }

PetaPoco/IExecuteAsync.cs

@@ -4,46 +4,60 @@
 namespace PetaPoco
 {
 #if ASYNC
+    /// <summary>
+    /// Defines an interface for asynchronously executing SQL commands and queries.
+    /// </summary>
+    /// <remarks>
+    /// This interface provides asynchronous methods for executing SQL non-query commands and scalar queries. It supports SQL commands and queries represented as strings or as <see cref="Sql">Sql Builder</see> objects.
+    /// </remarks>
     public interface IExecuteAsync
     {
-        /// <summary>
-        /// Async version of <see cref="IExecute.Execute(string,object[])" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteAsync(CancellationToken, string, object[])"/>
         Task<int> ExecuteAsync(string sql, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(Sql)" />.
+        /// Asynchronously executes a non-query command with a cancellation token.
         /// </summary>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="sql">The SQL statement to execute.</param>
+        /// <param name="args">Arguments to any embedded parameters in the SQL statement.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is the number of rows affected.</returns>
         Task<int> ExecuteAsync(CancellationToken cancellationToken, string sql, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IExecute.Execute(Sql)" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteAsync(CancellationToken, Sql)"/>
         Task<int> ExecuteAsync(Sql sql);
 
         /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(Sql)" />.
+        /// Asynchronously executes a non-query command with a cancellation token.
         /// </summary>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="sql">An Sql builder object representing the SQL statement and its arguments.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is the number of rows affected.</returns>
         Task<int> ExecuteAsync(CancellationToken cancellationToken, Sql sql);
 
-        /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(string,object[])" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteScalarAsync(CancellationToken, string, object[])"/>
         Task<T> ExecuteScalarAsync<T>(string sql, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(Sql)" />.
+        /// Asynchronously executes the query with a cancellation token and returns the first column of the first row in the result set.
         /// </summary>
+        /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="sql">The SQL query to execute.</param>
+        /// <param name="args">Arguments to any embedded parameters in the SQL statement.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is the scalar value cast to <typeparamref name="T"/>.</returns>
         Task<T> ExecuteScalarAsync<T>(CancellationToken cancellationToken, string sql, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(Sql)" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteScalarAsync(CancellationToken, Sql)"/>
         Task<T> ExecuteScalarAsync<T>(Sql sql);
 
         /// <summary>
-        /// Async version of <see cref="IExecute.ExecuteScalar{T}(Sql)" />.
+        /// Asynchronously executes the query with a cancellation token and returns the first column of the first row in the result set.
         /// </summary>
+        /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="sql">An Sql builder object representing the SQL query and its arguments.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is the scalar value cast to <typeparamref name="T"/>.</returns>
         Task<T> ExecuteScalarAsync<T>(CancellationToken cancellationToken, Sql sql);
     }
 #endif

PetaPoco/IStoredProc.cs

@@ -1,57 +1,57 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 
 namespace PetaPoco
 {
     /// <summary>
-    /// Defines methods for executing stored procedures.
+    /// Defines an interface for executing stored procedures.
     /// </summary>
     public interface IStoredProc
     {
         /// <summary>
-        /// Runs a stored procedure, returning the results as an IEnumerable collection.
+        /// Executes a stored procedure and returns the result as an IEnumerable of type T.
         /// </summary>
         /// <remarks>
         /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
         /// </remarks>
         /// <typeparam name="T">The Type representing a row in the result set.</typeparam>
-        /// <param name="storedProcedureName">The name of the stored procedure to run.</param>
-        /// <param name="args">Arguments for the stored procedure.</param>
-        /// <returns>An IEnumerable collection of result records.</returns>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>An IEnumerable of type T containing the result set of the stored procedure.</returns>
         IEnumerable<T> QueryProc<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Runs a stored procedure, returning the results as typed list.
+        /// Executes a stored procedure and returns the result as a List of type T.
         /// </summary>
         /// <remarks>
         /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
         /// </remarks>
         /// <typeparam name="T">The Type representing a row in the result set.</typeparam>
-        /// <param name="storedProcedureName">The name of the stored procedure to run.</param>
-        /// <param name="args">Arguments for the stored procedure.</param>
-        /// <returns>A List holding the results of the query.</returns>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A List of type T containing the result set of the stored procedure.</returns>
         List<T> FetchProc<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Executes a stored procedure and returns the first column of the first row in the result set..
+        /// Executes a stored procedure and returns the first column of the first row in the result set as type T.
         /// </summary>
         /// <remarks>
         /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
         /// </remarks>
         /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
-        /// <param name="storedProcedureName">The name of the stored procedure to run.</param>
-        /// <param name="args">Arguments for the stored procedure.</param>
-        /// <returns>The scalar value cast to T.</returns>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>The scalar result of the stored procedure of type T.</returns>
         T ExecuteScalarProc<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Executes a non-query stored procedure.
+        /// Executes a non-query stored procedure and returns the number of rows affected.
         /// </summary>
         /// <remarks>
         /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
         /// </remarks>
-        /// <param name="storedProcedureName">The name of the stored procedure to run.</param>
-        /// <param name="args">Arguments for the stored procedure.</param>
-        /// <returns>The number of rows affected.</returns>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>The number of rows affected by the stored procedure.</returns>
         int ExecuteNonQueryProc(string storedProcedureName, params object[] args);
     }
 }

PetaPoco/IStoredProcAsync.cs

@@ -5,56 +5,89 @@
 
 namespace PetaPoco
 {
+    /// <summary>
+    /// Defines an interface for asynchronously executing stored procedures.
+    /// </summary>
     public interface IStoredProcAsync
     {
-        /// <summary>
-        /// Async version of <see cref="IStoredProc.QueryProc{T}" />.
-        /// </summary>
+        /// <inheritdoc cref="QueryProcAsync{T}(Action{T}, CancellationToken, string, object[])"/>
         Task QueryProcAsync<T>(Action<T> receivePocoCallback, string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IStoredProc.QueryProc{T}" />.
+        /// Asynchronously executes a stored procedure and returns the result as an IAsyncReader of type T.
         /// </summary>
+        /// <remarks>
+        /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
+        /// </remarks>
+        /// <typeparam name="T">The Type representing a row in the result set.</typeparam>
+        /// <param name="receivePocoCallback">An action callback to execute on each POCO in the result set.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A task representing the asynchronous operation. The task result is an IAsyncReader of type T containing the result set of the stored procedure.</returns>
         Task QueryProcAsync<T>(Action<T> receivePocoCallback, CancellationToken cancellationToken, string storedProcedureName, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IStoredProc.QueryProc{T}" />.
-        /// </summary>
+        /// <inheritdoc cref="QueryProcAsync{T}(CancellationToken, string, object[])"/>
         Task<IAsyncReader<T>> QueryProcAsync<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IStoredProc.QueryProc{T}" />.
+        /// Asynchronously executes a stored procedure and returns the result as an IAsyncReader of type T.
         /// </summary>
+        /// <remarks>
+        /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
+        /// </remarks>
+        /// <typeparam name="T">The Type representing a row in the result set.</typeparam>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A task representing the asynchronous operation. The task result is an IAsyncReader of type T containing the result set of the stored procedure.</returns>
         Task<IAsyncReader<T>> QueryProcAsync<T>(CancellationToken cancellationToken, string storedProcedureName, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IStoredProc.FetchProc{T}" />.
-        /// </summary>
+        /// <inheritdoc cref="FetchProcAsync{T}(CancellationToken, string, object[])"/>
         Task<List<T>> FetchProcAsync<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IStoredProc.FetchProc{T}" />.
+        /// Asynchronously executes a stored procedure and returns the result as a List of type T.
         /// </summary>
+        /// <remarks>
+        /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
+        /// </remarks>
+        /// <typeparam name="T">The Type representing a row in the result set.</typeparam>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A task representing the asynchronous operation. The task result is a List of type T containing the result set of the stored procedure.</returns>
         Task<List<T>> FetchProcAsync<T>(CancellationToken cancellationToken, string storedProcedureName, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IStoredProc.ExecuteScalarProc{T}" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteScalarProcAsync{T}(CancellationToken, string, object[])"/>
         Task<T> ExecuteScalarProcAsync<T>(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IStoredProc.ExecuteScalarProc{T}" />.
+        /// Asynchronously executes a stored procedure and returns the first column of the first row in the result set as type T.
         /// </summary>
+        /// <remarks>
+        /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
+        /// </remarks>
+        /// <typeparam name="T">The type that the result value should be cast to.</typeparam>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A task representing the asynchronous operation. The task result is the scalar result of the stored procedure of type T.</returns>
         Task<T> ExecuteScalarProcAsync<T>(CancellationToken cancellationToken, string storedProcedureName, params object[] args);
 
-        /// <summary>
-        /// Async version of <see cref="IStoredProc.ExecuteNonQueryProc" />.
-        /// </summary>
+        /// <inheritdoc cref="ExecuteNonQueryProcAsync(CancellationToken, string, object[])"/>
         Task<int> ExecuteNonQueryProcAsync(string storedProcedureName, params object[] args);
 
         /// <summary>
-        /// Async version of <see cref="IStoredProc.ExecuteNonQueryProc" />.
+        /// Asynchronously executes a non-query stored procedure and returns the number of rows affected.
         /// </summary>
+        /// <remarks>
+        /// For any arguments which are POCOs, each readable property will be turned into a named parameter for the stored procedure. Arguments which are IDbDataParameters will be passed through. Any other argument types will throw an exception.
+        /// </remarks>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="storedProcedureName">The name of the stored procedure to execute.</param>
+        /// <param name="args">The arguments to pass to the stored procedure.</param>
+        /// <returns>A task representing the asynchronous operation. The task result is the number of rows affected by the stored procedure.</returns>
         Task<int> ExecuteNonQueryProcAsync(CancellationToken cancellationToken, string storedProcedureName, params object[] args);
     }
 }