Documentation: Rainbow

Dapper.Rainbow/Database.Async.cs

@@ -13,10 +13,10 @@ public abstract partial class Database<TDatabase> where TDatabase : Database<TDa
         public partial class Table<T, TId>
         {
             /// <summary>
-            /// Insert a row into the db asynchronously
+            /// Insert a row into the db asynchronously.
             /// </summary>
-            /// <param name="data">Either DynamicParameters or an anonymous type or concrete type</param>
-            /// <returns></returns>
+            /// <param name="data">Either DynamicParameters or an anonymous type or concrete type.</param>
+            /// <returns>The Id of the inserted row.</returns>
             public virtual async Task<int?> InsertAsync(dynamic data)
             {
                 var o = (object)data;
@@ -31,11 +31,11 @@ public partial class Table<T, TId>
             }
 
             /// <summary>
-            /// Update a record in the DB asynchronously
+            /// Update a record in the DB asynchronously.
             /// </summary>
-            /// <param name="id"></param>
-            /// <param name="data"></param>
-            /// <returns></returns>
+            /// <param name="id">The Id of the record to update.</param>
+            /// <param name="data">The new record.</param>
+            /// <returns>The number of affeced rows.</returns>
             public Task<int> UpdateAsync(TId id, dynamic data)
             {
                 List<string> paramNames = GetParamNames((object)data);
@@ -52,42 +52,34 @@ public Task<int> UpdateAsync(TId id, dynamic data)
             }
 
             /// <summary>
-            /// Delete a record for the DB asynchronously
+            /// Asynchronously deletes a record for the DB.
             /// </summary>
-            /// <param name="id"></param>
-            /// <returns></returns>
-            public async Task<bool> DeleteAsync(TId id)
-            {
-                return (await database.ExecuteAsync("delete from " + TableName + " where Id = @id", new { id }).ConfigureAwait(false)) > 0;
-            }
+            /// <param name="id">The Id of the record to delete.</param>
+            /// <returns>The number of rows affected.</returns>
+            public async Task<bool> DeleteAsync(TId id) =>
+                (await database.ExecuteAsync("delete from " + TableName + " where Id = @id", new { id }).ConfigureAwait(false)) > 0;
 
             /// <summary>
-            /// Asynchronously gets a record with a particular Id from the DB 
+            /// Asynchronously gets a record with a particular Id from the DB.
             /// </summary>
             /// <param name="id">The primary key of the table to fetch.</param>
             /// <returns>The record with the specified Id.</returns>
-            public Task<T> GetAsync(TId id)
-            {
-                return database.QueryFirstOrDefaultAsync<T>("select * from " + TableName + " where Id = @id", new { id });
-            }
+            public Task<T> GetAsync(TId id) =>
+                database.QueryFirstOrDefaultAsync<T>("select * from " + TableName + " where Id = @id", new { id });
 
             /// <summary>
             /// Asynchronously gets the first row from this table (order determined by the database provider).
             /// </summary>
             /// <returns>Data from the first table row.</returns>
-            public virtual Task<T> FirstAsync()
-            {
-                return database.QueryFirstOrDefaultAsync<T>("select top 1 * from " + TableName);
-            }
+            public virtual Task<T> FirstAsync() =>
+                database.QueryFirstOrDefaultAsync<T>("select top 1 * from " + TableName);
 
             /// <summary>
             /// Asynchronously gets the all rows from this table.
             /// </summary>
             /// <returns>Data from all table rows.</returns>
-            public Task<IEnumerable<T>> AllAsync()
-            {
-                return database.QueryAsync<T>("select * from " + TableName);
-            }
+            public Task<IEnumerable<T>> AllAsync() =>
+                database.QueryAsync<T>("select * from " + TableName);
         }
 
         /// <summary>
@@ -96,10 +88,8 @@ public Task<IEnumerable<T>> AllAsync()
         /// <param name="sql">The SQL to execute.</param>
         /// <param name="param">The parameters to use.</param>
         /// <returns>The number of rows affected.</returns>
-        public Task<int> ExecuteAsync(string sql, dynamic param = null)
-        {
-            return _connection.ExecuteAsync(sql, param as object, _transaction, this._commandTimeout);
-        }
+        public Task<int> ExecuteAsync(string sql, dynamic param = null) =>
+            _connection.ExecuteAsync(sql, param as object, _transaction, this._commandTimeout);
 
         /// <summary>
         /// Asynchronously queries the current database.
@@ -108,10 +98,8 @@ public Task<int> ExecuteAsync(string sql, dynamic param = null)
         /// <param name="sql">The SQL to execute.</param>
         /// <param name="param">The parameters to use.</param>
         /// <returns>An enumerable of <typeparamref name="T"/> for the rows fetched.</returns>
-        public Task<IEnumerable<T>> QueryAsync<T>(string sql, dynamic param = null)
-        {
-            return _connection.QueryAsync<T>(sql, param as object, _transaction, _commandTimeout);
-        }
+        public Task<IEnumerable<T>> QueryAsync<T>(string sql, dynamic param = null) =>
+            _connection.QueryAsync<T>(sql, param as object, _transaction, _commandTimeout);
 
         /// <summary>
         /// Asynchronously queries the current database for a single record.
@@ -120,42 +108,86 @@ public Task<IEnumerable<T>> QueryAsync<T>(string sql, dynamic param = null)
         /// <param name="sql">The SQL to execute.</param>
         /// <param name="param">The parameters to use.</param>
         /// <returns>An enumerable of <typeparamref name="T"/> for the rows fetched.</returns>
-        public Task<T> QueryFirstOrDefaultAsync<T>(string sql, dynamic param = null)
-        {
-            return _connection.QueryFirstOrDefaultAsync<T>(sql, param as object, _transaction, _commandTimeout);
-        }
+        public Task<T> QueryFirstOrDefaultAsync<T>(string sql, dynamic param = null) =>
+            _connection.QueryFirstOrDefaultAsync<T>(sql, param as object, _transaction, _commandTimeout);
 
         /// <summary>
-        /// Perform an asynchronous multi mapping query with 2 input parameters
+        /// Perform a asynchronous multi-mapping query with 2 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
-        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TReturn>(string sql, Func<TFirst, TSecond, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null)
-        {
-            return _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
-        }
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
+        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TReturn>(string sql, Func<TFirst, TSecond, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
+            _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform an asynchronous multi mapping query with 3 input parameters
+        /// Perform a asynchronous multi-mapping query with 3 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
-        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TReturn>(string sql, Func<TFirst, TSecond, TThird, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null)
-        {
-            return _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
-        }
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
+        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TReturn>(string sql, Func<TFirst, TSecond, TThird, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
+            _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform an asynchronous multi mapping query with 4 input parameters
+        /// Perform a asynchronous multi-mapping query with 4 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
-        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TFourth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null)
-        {
-            return _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
-        }
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TFourth">The fourth type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
+        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TFourth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
+            _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform an asynchronous multi mapping query with 5 input parameters
+        /// Perform a asynchronous multi-mapping query with 5 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
-        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TFourth, TFifth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TFifth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null)
-        {
-            return _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
-        }
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TFourth">The fourth type in the recordset.</typeparam>
+        /// <typeparam name="TFifth">The fifth type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
+        public Task<IEnumerable<TReturn>> QueryAsync<TFirst, TSecond, TThird, TFourth, TFifth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TFifth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
+            _connection.QueryAsync(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
         /// Execute a query asynchronously using .NET 4.5 Task.
@@ -163,18 +195,19 @@ public Task<T> QueryFirstOrDefaultAsync<T>(string sql, dynamic param = null)
         /// <param name="sql">The SQL to execute.</param>
         /// <param name="param">The parameters to use.</param>
         /// <remarks>Note: each row can be accessed via "dynamic", or by casting to an IDictionary&lt;string,object&gt;</remarks>
-        public Task<IEnumerable<dynamic>> QueryAsync(string sql, dynamic param = null)
-        {
-            return _connection.QueryAsync(sql, param as object, _transaction);
-        }
+        public Task<IEnumerable<dynamic>> QueryAsync(string sql, dynamic param = null) =>
+            _connection.QueryAsync(sql, param as object, _transaction);
 
         /// <summary>
-        /// Execute a command that returns multiple result sets, and access each in turn
+        /// Execute a command that returns multiple result sets, and access each in turn.
         /// </summary>
-        public Task<SqlMapper.GridReader> QueryMultipleAsync(string sql, dynamic param = null, IDbTransaction transaction = null, int? commandTimeout = null, CommandType? commandType = null)
-        {
-            return SqlMapper.QueryMultipleAsync(_connection, sql, param, transaction, commandTimeout, commandType);
-        }
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <param name="commandType">Is it a stored proc or a batch?</param>
+        public Task<SqlMapper.GridReader> QueryMultipleAsync(string sql, dynamic param = null, IDbTransaction transaction = null, int? commandTimeout = null, CommandType? commandType = null) =>
+            SqlMapper.QueryMultipleAsync(_connection, sql, param, transaction, commandTimeout, commandType);
     }
 }
 #endif
\ No newline at end of file

Dapper.Rainbow/Database.cs

@@ -363,26 +363,80 @@ private bool TableExists(string name)
             _connection.QueryFirstOrDefault<T>(sql, param as object, _transaction, _commandTimeout);
 
         /// <summary>
-        /// Perform a multi mapping query with 2 input parameters
+        /// Perform a multi-mapping query with 2 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
         public IEnumerable<TReturn> Query<TFirst, TSecond, TReturn>(string sql, Func<TFirst, TSecond, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
             _connection.Query(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform a multi mapping query with 3 input parameters
+        /// Perform a multi-mapping query with 3 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
         public IEnumerable<TReturn> Query<TFirst, TSecond, TThird, TReturn>(string sql, Func<TFirst, TSecond, TThird, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
             _connection.Query(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform a multi mapping query with 4 input parameters
+        /// Perform a multi-mapping query with 4 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TFourth">The fourth type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
         public IEnumerable<TReturn> Query<TFirst, TSecond, TThird, TFourth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
             _connection.Query(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
         /// <summary>
-        /// Perform a multi mapping query with 5 input parameters
+        /// Perform a multi-mapping query with 5 input types. 
+        /// This returns a single type, combined from the raw types via <paramref name="map"/>.
         /// </summary>
+        /// <typeparam name="TFirst">The first type in the recordset.</typeparam>
+        /// <typeparam name="TSecond">The second type in the recordset.</typeparam>
+        /// <typeparam name="TThird">The third type in the recordset.</typeparam>
+        /// <typeparam name="TFourth">The fourth type in the recordset.</typeparam>
+        /// <typeparam name="TFifth">The fifth type in the recordset.</typeparam>
+        /// <typeparam name="TReturn">The combined type to return.</typeparam>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="map">The function to map row types to the return type.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="buffered">Whether to buffer the results in memory.</param>
+        /// <param name="splitOn">The field we should split and read the second object from (default: "Id").</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <returns>An enumerable of <typeparamref name="TReturn"/>.</returns>
         public IEnumerable<TReturn> Query<TFirst, TSecond, TThird, TFourth, TFifth, TReturn>(string sql, Func<TFirst, TSecond, TThird, TFourth, TFifth, TReturn> map, dynamic param = null, IDbTransaction transaction = null, bool buffered = true, string splitOn = "Id", int? commandTimeout = null) =>
             _connection.Query(sql, map, param as object, transaction, buffered, splitOn, commandTimeout);
 
@@ -397,8 +451,13 @@ private bool TableExists(string name)
             _connection.Query(sql, param as object, _transaction, buffered);
 
         /// <summary>
-        /// Execute a command that returns multiple result sets, and access each in turn
+        /// Execute a command that returns multiple result sets, and access each in turn.
         /// </summary>
+        /// <param name="sql">The SQL to execute for this query.</param>
+        /// <param name="param">The parameters to use for this query.</param>
+        /// <param name="transaction">The transaction to use for this query.</param>
+        /// <param name="commandTimeout">Number of seconds before command execution timeout.</param>
+        /// <param name="commandType">Is it a stored proc or a batch?</param>
         public SqlMapper.GridReader QueryMultiple(string sql, dynamic param = null, IDbTransaction transaction = null, int? commandTimeout = null, CommandType? commandType = null) =>
             SqlMapper.QueryMultiple(_connection, sql, param, transaction, commandTimeout, commandType);