Fix API documents (#4)

SqlBind/.editorconfig

@@ -242,3 +242,4 @@ dotnet_diagnostic.SA1013.severity = none
 dotnet_diagnostic.SA1002.severity = none
 dotnet_diagnostic.SA1010.severity = none
 dotnet_diagnostic.SA1518.severity = none
+dotnet_diagnostic.SA1004.severity = none

SqlBind/Maroontress/SqlBind/DeleteFrom.cs

@@ -3,7 +3,7 @@ namespace Maroontress.SqlBind;
 using System.Collections.Generic;
 
 /// <summary>
-/// Represents the <c>DELETE</c> statement in SQL.
+/// Represents the <c>DELETE</c> statement.
 /// </summary>
 /// <typeparam name="T">
 /// The type of the class qualified with the <see cref="TableAttribute"/>.

SqlBind/Maroontress/SqlBind/Query.cs

@@ -44,18 +44,37 @@ Select<T> Select<T>(params string[] columns)
         where T : notnull;
 
     /// <summary>
-    /// Gets the <see cref="Update"/> object to update the specified table.
+    /// Gets the <see cref="SqlBind.Update"/> object to update the specified
+    /// table.
     /// </summary>
     /// <typeparam name="T">
     /// The type qualified with <see cref="TableAttribute"/>.
     /// </typeparam>
     /// <param name="alias">
-    /// The alias of the table name, which is used in the <c>Where</c> clause
-    /// (see <see cref="UpdateWhere"/>).
+    /// The alias of the table name, which can be used in the <c>Where</c>
+    /// clause (see <see cref="UpdateSet.Where(string)"/>).
     /// </param>
     /// <returns>
-    /// The <see cref="Update"/> object.
+    /// The <see cref="SqlBind.Update"/> object.
     /// </returns>
+    /// <example>
+    /// <code>
+    /// var kit = new TransactionKit(
+    ///     "update_example.db", m => Console.WriteLine(m()));
+    /// var map = new Dictionary&lt;string, object>()
+    /// {
+    ///     ["$id"] = 2L,
+    ///     ["$newState"] = "Closed",
+    /// };
+    /// kit.Execute(q =>
+    /// {
+    ///     q.Update&lt;Issue>("i")
+    ///         .Set("state = $newState")
+    ///         .Where("i.id = $id")
+    ///         .Execute(map);
+    /// });
+    /// </code>
+    /// </example>
     Update Update<T>(string alias)
         where T : notnull;
 

SqlBind/Maroontress/SqlBind/Select.cs

@@ -3,7 +3,7 @@
 namespace Maroontress.SqlBind;
 
 /// <summary>
-/// Represents the <c>SELECT</c> statement in SQL.
+/// Represents the <c>SELECT</c> statement.
 /// </summary>
 /// <typeparam name="T">
 /// The type of the class representing any row of the result of the query.

SqlBind/Maroontress/SqlBind/SelectFrom.cs

@@ -5,8 +5,8 @@ namespace Maroontress.SqlBind;
 using System.Collections.Generic;
 
 /// <summary>
-/// Represents the <c>SELECT</c> statement in SQL without a <c>WHERE</c>
-/// clause. It can end with a <c>INNER JOIN</c> clause.
+/// Represents the <c>SELECT</c> statement without a <c>WHERE</c> clause. It
+/// can end with a <c>INNER JOIN</c> clause.
 /// </summary>
 /// <typeparam name="T">
 /// The type of the class representing any row of the result of the query.

SqlBind/Maroontress/SqlBind/TerminalOperation.cs

@@ -3,7 +3,7 @@ namespace Maroontress.SqlBind;
 using System.Collections.Generic;
 
 /// <summary>
-/// Represents the executable <c>SELECT</c> statement in SQL.
+/// Represents the executable <c>SELECT</c> statement.
 /// </summary>
 /// <typeparam name="T">
 /// The type of the class representing any row of the result of the query.

SqlBind/Maroontress/SqlBind/Update.cs

@@ -1,15 +1,22 @@
 namespace Maroontress.SqlBind;
 
+using System.Collections.Generic;
+
 /// <summary>
-/// Represents the <c>UPDATE</c> statement in SQL.
+/// Represents the <c>UPDATE</c> statement.
 /// </summary>
 public interface Update
 {
     /// <summary>
     /// Gets a new <see cref="UpdateSet"/> object.
     /// </summary>
     /// <param name="expr">
-    /// The expression in the <c>SET</c> clause.
+    /// The expression in the <c>SET</c> clause. Note that this expression must
+    /// not contain the <c>alias</c> specified in the <see
+    /// cref="Query.Update{T}(string)"/> method. The values of the parameters
+    /// in the expression can be specified with the <see
+    /// cref="UpdateTerminalOperation.Execute(IReadOnlyDictionary{string,
+    /// object})"/> method.
     /// </param>
     /// <returns>
     /// The new <see cref="UpdateSet"/> object.

SqlBind/Maroontress/SqlBind/UpdateSet.cs

@@ -1,7 +1,9 @@
 namespace Maroontress.SqlBind;
 
+using System.Collections.Generic;
+
 /// <summary>
-/// Represents an operation that sets the values in an update statement.
+/// Represents the <c>SET</c> clause in an <c>UPDATE</c> statement.
 /// </summary>
 public interface UpdateSet
     : UpdateTerminalOperation
@@ -12,9 +14,12 @@ public interface UpdateSet
     /// <c>WHERE</c> ... clause.
     /// </summary>
     /// <param name="expr">
-    /// The expression of the <c>WHERE</c> clause. Note that this expression
-    /// should not contain <c>alias</c> specified in the <see
-    /// cref="Query.Update{T}(string)"/>.
+    /// The expression of the <c>WHERE</c> clause. This expression can contain
+    /// the <c>alias</c> specified in the <see cref="Query.Update{T}(string)"/>
+    /// method. The values of the parameters in the expression can be specified
+    /// with the <see
+    /// cref="UpdateTerminalOperation.Execute(IReadOnlyDictionary{string,
+    /// object})"/> method.
     /// </param>
     /// <returns>
     /// The new <see cref="UpdateWhere"/> object.

SqlBind/Maroontress/SqlBind/UpdateTerminalOperation.cs

@@ -3,17 +3,19 @@ namespace Maroontress.SqlBind;
 using System.Collections.Generic;
 
 /// <summary>
-/// Represents the executable <c>UPDATE</c> statement in SQL.
+/// Represents the executable <c>UPDATE</c> statement.
 /// </summary>
 public interface UpdateTerminalOperation
 {
     /// <summary>
-    /// Executes the update operation with the specified parameters.
+    /// Executes the <c>UPDATE</c> statement with the specified parameters.
     /// </summary>
     /// <param name="parameters">
-    /// Immutable key-value pairs. The parameters in the <c>Set</c> and
-    /// <c>Where</c> clauses must contain all the keys. Each value must be of
-    /// the appropriate type.
+    /// Immutable key-value pairs. All parameter names in the <c>SET</c> and
+    /// <c>WHERE</c> clauses must be included in <c>parameters</c> as keys.
+    /// Each value must be of the appropriate type.
     /// </param>
+    /// <seealso cref="Update.Set(string)"/>
+    /// <seealso cref="UpdateSet.Where(string)"/>
     void Execute(IReadOnlyDictionary<string, object> parameters);
 }

SqlBind/Maroontress/SqlBind/Where.cs

@@ -1,7 +1,7 @@
 namespace Maroontress.SqlBind;
 
 /// <summary>
-/// Represents the <c>SELECT</c> ... <c>WHERE</c> ... statement in SQL.
+/// Represents the <c>WHERE</c> clause in a <c>SELECT</c> statement.
 /// </summary>
 /// <typeparam name="T">
 /// The type of the class representing any row of the result of the query.