update xml doc comments:

- ColumnInfo.cs
- IGridReader.cs
- PocoData.cs
- AsyncReader.cs
- DatabaseConfigurationExtensions.cs
- Interfaces (db operations)
- Attribute classes

add missing `#if ASYNC` scopes, fix disparite usage of `!NET40` to wrap async methods:
- IAlterPocoAsync.cs
- IConnection.cs
- IStoredProcAsync.cs

renamed parameter names for variables and callback methods:
- DatabaseConfigurationExtensions.cs
  `configure`->`cofigurer`
- IGridReader.cs
  `func`->`projector`
- IQuery.cs
  `cb`->`projector`
  `itemsPerPage`->`maxItemsPerPage`
  `sqlCount`->`countSql` (match countArgs format)
  `sqlPage`->`pageSql` (match pageArgs format)
  `primaryKey`->`pocoOrPrimaryKey` (selective for specific context...eg `Exists`, `ExistsAsync`)
- IQueryAsync.cs
  `receivePocoCallback`->`action`
  `itemsPerPage`->`maxItemsPerPage`
  `sqlCount`->`countSql` (match countArgs format)
  `sqlPage`->`pageSql` (match pageArgs format)
- IStoredProcAsync.cs
  `receivePocoCallback`->`action`
- ParametersHelper.cs
  `args_src`->`srcArgs` (consistent naming convention for public visible parameters)
  `args_dest`->`destArgs` (consistent naming convention for public visible parameters)

renamed type names:
- DatabaseConfigurationExtensions.cs
  `T`->`TProvider`
  `T`->`TMapper`
- IGridReader.cs
  `TRet`->`TResult`
- IQuery.cs
  `TRet`->`TResult`
- IQueryAsync.cs

other notable changes
- bugs: see todo comments
- Page{T}, IQuery, IQueryAsync: switch from "itemsPerPage" to "maxItemsPerPage"

PetaPoco/Attributes/ColumnAttribute.cs

@@ -48,8 +48,8 @@ public class ColumnAttribute : Attribute
         /// <remarks>
         /// When set, this template is used for generating the INSERT portion of the SQL statement instead of the default
         /// <br/><c>String.Format("{0}{1}", paramPrefix, index)</c>.
-        /// <para/>Setting this allows database-related interactions, such as:
-        /// <br/><c>String.Format("CAST({0}{1} AS JSON)", paramPrefix, index)</c>.
+        /// <para>Setting this allows database-related interactions, such as:
+        /// <br/><c>String.Format("CAST({0}{1} AS JSON)", paramPrefix, index)</c>.</para>
         /// </remarks>
         public string InsertTemplate { get; set; }
 
@@ -59,8 +59,8 @@ public class ColumnAttribute : Attribute
         /// <remarks>
         /// When set, this template is used for generating the UPDATE portion of the SQL statement instead of the default
         /// <br/><c>String.Format("{0} = {1}{2}", colName, paramPrefix, index)</c>.
-        /// <para/>Setting this allows database-related interactions, such as:
-        /// <br/><c>String.Format("{0} = CAST({1}{2} AS JSON)", colName, paramPrefix, index)</c>
+        /// <para>Setting this allows database-related interactions, such as:
+        /// <br/><c>String.Format("{0} = CAST({1}{2} AS JSON)", colName, paramPrefix, index)</c></para>
         /// </remarks>
         public string UpdateTemplate { get; set; }
 

PetaPoco/Attributes/IgnoreAttribute.cs

@@ -7,7 +7,7 @@ namespace PetaPoco
     /// </summary>
     /// <remarks>
     /// Properties decorated with this attribute are completely ignored by PetaPoco, and do not participate in any database-related operations.
-    /// <para/>If you find yourself using this attribute excessively, consider instead decorating your POCO class with the <see cref="ExplicitColumnsAttribute"/>, and then marking the properties you want mapped with their appropriate column attribute.
+    /// <para>If you find yourself using this attribute excessively, consider instead decorating your POCO class with the <see cref="ExplicitColumnsAttribute"/>, and then marking the properties you want mapped with their appropriate column attribute.</para>
     /// </remarks>
     /// <seealso cref="ExplicitColumnsAttribute"/>
     [AttributeUsage(AttributeTargets.Property)]

PetaPoco/Attributes/PrimaryKeyAttribute.cs

@@ -12,7 +12,7 @@ namespace PetaPoco
     public class PrimaryKeyAttribute : Attribute
     {
         /// <summary>
-        /// Gets the column name.
+        /// Gets the column name in the database.
         /// </summary>
         public string Value { get; }
 
@@ -22,9 +22,9 @@ public class PrimaryKeyAttribute : Attribute
         public string SequenceName { get; set; }
 
         /// <summary>
-        /// Gets or sets whether the primary key column represented by this property is auto-incrementing in the database.
+        /// Gets or sets whether the primary key column represented by this property in the database is auto-incrementing.
+        /// Default is <see langword="true"/>.
         /// </summary>
-        /// <value>Default value is <see langword="true"/> (auto-incrementing).</value>
         public bool AutoIncrement { get; set; } = true;
 
         /// <summary>

PetaPoco/Attributes/ResultColumnAttribute.cs

@@ -23,7 +23,7 @@ public enum IncludeInAutoSelect
     /// </summary>
     /// <remarks>
     /// This attribute marks properties that are mapped to a column, but should not be involved in any mutating operations on the database. The property value is updated by queries from the database, but the database column it maps to will not be changed to reflect changes in this property.
-    /// <para/>Use the <see cref="IncludeInAutoSelect"/> property to dictate whether the decorated property is included in operations using PetaPoco's AutoSelect feature (default is <see cref="IncludeInAutoSelect.No"/>). AutoSelect queries are operations made using the "short form" syntax, without specifying the <c>SELECT [cols] FROM [table]</c> portion of the SQL statement. The inferred portion of the SQL statement is then automatically generated by PetaPoco based on generics or the called method's parameters.
+    /// <para>Use the <see cref="IncludeInAutoSelect"/> property to dictate whether the decorated property is included in operations using PetaPoco's AutoSelect feature (default is <see cref="IncludeInAutoSelect.No"/>). AutoSelect queries are operations made using the "short form" syntax, without specifying the <c>SELECT [cols] FROM [table]</c> portion of the SQL statement. The inferred portion of the SQL statement is then automatically generated by PetaPoco based on generics or the called method's parameters.</para>
     /// </remarks>
     [AttributeUsage(AttributeTargets.Property)]
     public class ResultColumnAttribute : ColumnAttribute

PetaPoco/Attributes/ValueConverterAttribute.cs

@@ -7,7 +7,7 @@ namespace PetaPoco
     /// </summary>
     /// <remarks>
     /// ValueConverters are used to implement custom two-way conversions between your POCO property data type, and the mapped database column's data type. They are ideal for implementing a custom conversion without requiring any changes to the mapper.
-    /// <para/>To provide a custom ValueConverter for a property, inherit from this class, and supply definitions for both conversion methods for your data type. Decorate the appropriate properties that require your ValueConverter with your derived class.
+    /// <para>To provide a custom ValueConverter for a property, inherit from this class, and supply definitions for both conversion methods for your data type. Decorate the appropriate properties that require your ValueConverter with your derived class.</para>
     /// </remarks>
     [AttributeUsage(AttributeTargets.Property)]
     public abstract class ValueConverterAttribute : Attribute

PetaPoco/Core/ColumnInfo.cs

@@ -22,14 +22,14 @@ public class ColumnInfo
         public string ColumnName { get; set; }
 
         /// <summary>
-        /// Gets or sets whether this column represents a property that should be updated in queries that include a user-supplied SELECT statement, but ignored in queries generated by AutoSelect. Result columns are always ignored in UPDATE and INSERT operations.
+        /// Gets or sets whether this column represents a property that should be updated in queries that include a user-supplied <c>SELECT</c> statement, but ignored in queries generated by AutoSelect. Result columns are always ignored in <c>UPDATE</c> and <c>INSERT</c> operations.
         /// </summary>
-        /// <value>If <see langword="true"/>, this property will be updated in SQL query operations containing a user-supplied SELECT statement, and ignored for all other database operations.</value>
+        /// <value>If <see langword="true"/>, this property will be updated in SQL query operations containing a user-supplied <c>SELECT</c> statement, and ignored for all other database operations.</value>
         /// <seealso cref="ResultColumnAttribute"/>
         public bool ResultColumn { get; set; }
 
         /// <summary>
-        /// Gets or sets whether this serves as a ResultColumn that is included with AutoSelect queries as well as queries containing user-supplied SELECT statements.
+        /// Gets or sets whether this serves as a ResultColumn that is included with AutoSelect queries as well as queries containing user-supplied <c>SELECT</c> statements.
         /// </summary>
         /// <value>If <see langword="true"/>, this property will be updated in all SQL queries, but ignored for all other database operations such as INSERT and UPDATE.</value>
         /// <seealso cref="ResultColumnAttribute.IncludeInAutoSelect"/>
@@ -69,25 +69,25 @@ public class ColumnInfo
         public bool ForceToUtc { get; set; }
 
         /// <summary>
-        /// Gets or sets the template used for INSERT operations.
+        /// Gets or sets the template used for <c>INSERT</c> operations.
         /// </summary>
         /// <remarks>
-        /// When set, this template is used for generating the INSERT portion of the SQL statement instead of the default
+        /// When set, this template is used for generating the <c>INSERT</c> portion of the SQL statement instead of the default
         /// <br/><c>String.Format("{0}{1}", paramPrefix, index)</c>.
-        /// <para/>Setting this allows database-related interactions, such as:
-        /// <br/><c>String.Format("CAST({0}{1} AS JSON)", paramPrefix, index)</c>.
+        /// <para>Setting this allows database-related interactions, such as:
+        /// <br/><c>String.Format("CAST({0}{1} AS JSON)", paramPrefix, index)</c>.</para>
         /// </remarks>
         /// <seealso cref="ColumnAttribute.InsertTemplate"/>
         public string InsertTemplate { get; set; }
 
         /// <summary>
-        /// Gets or sets the template used for UPDATE operations.
+        /// Gets or sets the template used for <c>UPDATE</c> operations.
         /// </summary>
         /// <remarks>
-        /// When set, this template is used for generating the UPDATE portion of the SQL statement instead of the default
+        /// When set, this template is used for generating the <c>UPDATE</c> portion of the SQL statement instead of the default
         /// <br/><c>String.Format("{0} = {1}{2}", colName, paramPrefix, index)</c>.
-        /// <para/>Setting this allows database-related interactions, such as:
-        /// <br/><c>String.Format("{0} = CAST({1}{2} AS JSON)", colName, paramPrefix, index)</c>
+        /// <para>Setting this allows database-related interactions, such as:
+        /// <br/><c>String.Format("{0} = CAST({1}{2} AS JSON)", colName, paramPrefix, index)</c></para>
         /// </remarks>
         /// <seealso cref="ColumnAttribute.UpdateTemplate"/>
         public string UpdateTemplate { get; set; }

PetaPoco/Core/ConventionMapper.cs

@@ -14,12 +14,12 @@ namespace PetaPoco
     public class ConventionMapper : IMapper
     {
         /// <summary>
-        /// Gets or sets the get sequence name logic.
+        /// Gets or sets the sequence name logic (for Oracle).
         /// </summary>
         public Func<Type, PropertyInfo, string> GetSequenceName { get; set; }
 
         /// <summary>
-        /// Gets or sets the inflect column name logic.
+        /// Gets or sets the inflected column name logic.
         /// </summary>
         public Func<IInflector, string, string> InflectColumnName { get; set; }
 

PetaPoco/Core/DatabaseProvider.cs

@@ -65,27 +65,27 @@ public virtual string BuildPageQuery(long skip, long take, SQLParts parts, ref o
         public virtual string GetInsertOutputClause(string primaryKeyName) => string.Empty;
 
         /// <inheritdoc />
-        public virtual object ExecuteInsert(Database database, IDbCommand cmd, string primaryKeyName)
+        public virtual object ExecuteInsert(Database db, IDbCommand cmd, string primaryKeyName)
         {
             cmd.CommandText += ";\nSELECT @@IDENTITY AS NewID;";
-            return ExecuteScalarHelper(database, cmd);
+            return ExecuteScalarHelper(db, cmd);
         }
 
 #if ASYNC
         /// <inheritdoc />
-        public virtual Task<object> ExecuteInsertAsync(CancellationToken cancellationToken, Database database, IDbCommand cmd, string primaryKeyName)
+        public virtual Task<object> ExecuteInsertAsync(CancellationToken cancellationToken, Database db, IDbCommand cmd, string primaryKeyName)
         {
             cmd.CommandText += ";\nSELECT @@IDENTITY AS NewID;";
-            return ExecuteScalarHelperAsync(cancellationToken, database, cmd);
+            return ExecuteScalarHelperAsync(cancellationToken, db, cmd);
         }
 #endif
 
         /// <summary>
-        /// Returns the DbProviderFactory.
+        /// Returns the provider factory from one or more specified assembly qualified names.
         /// </summary>
-        /// <param name="assemblyQualifiedNames">The assembly qualified name of the provider factory.</param>
-        /// <returns>The DbProviderFactory factory.</returns>
-        /// <exception cref="ArgumentException">Thrown when <paramref name="assemblyQualifiedNames" /> does not match a type.</exception>
+        /// <param name="assemblyQualifiedNames">One or more assembly qualified names of the provider factory.</param>
+        /// <returns>The provider factory.</returns>
+        /// <exception cref="ArgumentException">None of the <paramref name="assemblyQualifiedNames"/> match a type.</exception>
         protected DbProviderFactory GetFactory(params string[] assemblyQualifiedNames)
         {
             Type ft = null;
@@ -107,7 +107,7 @@ protected DbProviderFactory GetFactory(params string[] assemblyQualifiedNames)
         /// </summary>
         /// <typeparam name="T">Type of IProvider to be registered.</typeparam>
         /// <param name="initialString">String to be matched against the beginning of the provider name.</param>
-        /// <exception cref="ArgumentException">Thrown when <paramref name="initialString" /> is null, empty, or consists only of white space.</exception>
+        /// <exception cref="ArgumentException"><paramref name="initialString"/> is null, empty, or consists of only white space.</exception>
         public static void RegisterCustomProvider<T>(string initialString) where T : IProvider, new()
         {
             if (String.IsNullOrWhiteSpace(initialString))
@@ -129,26 +129,26 @@ private static IProvider GetCustomProvider(string name)
         internal static void ClearCustomProviders() => customProviders.Clear();
 
         /// <summary>
-        /// Instantiates a suitable IProvider instance based on the type and provider name.
+        /// Instantiates a suitable IProvider instance based on the specified provider's type.
         /// </summary>
-        /// <param name="type">The type name.</param>
-        /// <param name="allowDefault">A flag that when set allows the default <see cref="SqlServerDatabaseProvider" /> to be returned if not match is found.</param>
+        /// <param name="providerType">The provider's type name.</param>
+        /// <param name="allowDefault">A flag specifiying if the default <see cref="SqlServerDatabaseProvider"/> should be returned if no match is found.</param>
         /// <param name="connectionString">The connection string.</param>
-        /// <returns>The database provider.</returns>
-        /// <exception cref="ArgumentException">Thrown when the <paramref name="type" /> name cannot be matched to a provider.</exception>
-        internal static IProvider Resolve(Type type, bool allowDefault, string connectionString)
+        /// <returns>The resolved database provider.</returns>
+        /// <exception cref="ArgumentException">The <paramref name="providerType"/> name cannot be matched to a provider.</exception>
+        internal static IProvider Resolve(Type providerType, bool allowDefault, string connectionString)
         {
-            var typeName = type.Name;
+            var typeName = providerType.Name;
 
             // Try using type name first (more reliable)
             var custom = GetCustomProvider(typeName);
             if (custom != null)
                 return custom;
 
-            if (type.Namespace != null)
+            if (providerType.Namespace != null)
             {
-                if (typeName.Equals("SqlConnection") && type.Namespace.StartsWith("Microsoft.Data") ||
-                    type.Namespace.StartsWith("Microsoft.Data") && typeName.Equals("SqlClientFactory"))
+                if (typeName.Equals("SqlConnection") && providerType.Namespace.StartsWith("Microsoft.Data") ||
+                    providerType.Namespace.StartsWith("Microsoft.Data") && typeName.Equals("SqlClientFactory"))
                     return Singleton<SqlServerMsDataDatabaseProvider>.Instance;
             }
 
@@ -187,19 +187,19 @@ internal static IProvider Resolve(Type type, bool allowDefault, string connectio
             }
 
             if (!allowDefault)
-                throw new ArgumentException($"Could not match `{type.FullName}` to a provider.", nameof(type));
+                throw new ArgumentException($"Could not match `{providerType.FullName}` to a provider.", nameof(providerType));
 
             // Assume SQL Server
             return Singleton<SqlServerDatabaseProvider>.Instance;
         }
 
         /// <summary>
-        /// Instantiates a suitable IProvider instance based on the type and provider name.
+        /// Instantiates a suitable IProvider instance based on the specified provider name.
         /// </summary>
         /// <param name="providerName">The provider name.</param>
-        /// <param name="allowDefault">A flag that when set allows the default <see cref="SqlServerDatabaseProvider" /> to be returned if not match is found.</param>
+        /// <param name="allowDefault">A flag specifiying if the default <see cref="SqlServerDatabaseProvider"/> should be returned if no match is found.</param>
         /// <param name="connectionString">The connection string.</param>
-        /// <returns>The database type.</returns>
+        /// <returns>The resolved database provider.</returns>
         internal static IProvider Resolve(string providerName, bool allowDefault, string connectionString)
         {
             // Try again with provider name
@@ -255,10 +255,10 @@ internal static IProvider Resolve(string providerName, bool allowDefault, string
         }
 
         /// <summary>
-        /// Unwraps a wrapped <see cref="DbProviderFactory" />.
+        /// Unwraps the specified wrapped provider factory/>.
         /// </summary>
         /// <param name="factory">The factory to unwrap.</param>
-        /// <returns>The unwrapped factory or the original factory if no wrapping occurred.</returns>
+        /// <returns>The unwrapped factory, or the original factory if no wrapping occurred.</returns>
         internal static DbProviderFactory Unwrap(DbProviderFactory factory)
         {
             if (!(factory is IServiceProvider sp))
@@ -274,14 +274,39 @@ internal static DbProviderFactory Unwrap(DbProviderFactory factory)
             }
         }
 
+        /// <summary>
+        /// Executes a non-query command.
+        /// </summary>
+        /// <param name="db">The database instance on which to execute the command.</param>
+        /// <param name="cmd">The SQL command to execute.</param>
         protected void ExecuteNonQueryHelper(Database db, IDbCommand cmd) => db.ExecuteNonQueryHelper(cmd);
 
+        /// <summary>
+        /// Executes a query command and returns the first column of the first row in the result set.
+        /// </summary>
+        /// <param name="db">The database instance on which to execute the command.</param>
+        /// <param name="cmd">The SQL command to execute.</param>
+        /// <returns>The first column of the first row in the result set.</returns>
         protected object ExecuteScalarHelper(Database db, IDbCommand cmd) => db.ExecuteScalarHelper(cmd);
 
 #if ASYNC
+        /// <summary>
+        /// Asynchronously executes a non-query command.
+        /// </summary>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="db">The database instance on which to execute the command.</param>
+        /// <param name="cmd">The SQL command to execute.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         protected Task ExecuteNonQueryHelperAsync(CancellationToken cancellationToken, Database db, IDbCommand cmd)
             => db.ExecuteNonQueryHelperAsync(cancellationToken, cmd);
 
+        /// <summary>
+        /// Asynchronously executes a query command and returns the first column of the first row in the result set.
+        /// </summary>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <param name="db">The database instance on which to execute the command.</param>
+        /// <param name="cmd">The SQL command to execute.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is the first column of the first row in the result set.</returns>
         protected Task<object> ExecuteScalarHelperAsync(CancellationToken cancellationToken, Database db, IDbCommand cmd)
             => db.ExecuteScalarHelperAsync(cancellationToken, cmd);
 #endif