Add notes on experimental APIs.

bgrainger · bgrainger · commit af5dcf29ce5a · 2020-07-11T10:21:48.000-07:00
diff --git a/docs/content/api/MySqlConnector/MySqlBatchType.md b/docs/content/api/MySqlConnector/MySqlBatchType.md
@@ -70,6 +70,10 @@ public sealed class MySqlBatch : IDisposable
 | [Prepare](../MySqlBatch/Prepare/)() |  |
 | [PrepareAsync](../MySqlBatch/PrepareAsync/)(…) |  |
 
+## Remarks
+
+The proposed ADO.NET API that [`MySqlBatch`](../MySqlBatchType/) is based on is not finalized. This API is experimental and may change in the future.
+
 ## See Also
 
 * namespace [MySqlConnector](../../MySqlConnectorNamespace/)
diff --git a/docs/content/api/MySqlConnector/MySqlBulkCopyType.md b/docs/content/api/MySqlConnector/MySqlBulkCopyType.md
@@ -44,7 +44,9 @@ public sealed class MySqlBulkCopy
 
 ## Remarks
 
-Note: This API is a unique feature of MySqlConnector; you must [switch to MySqlConnector](https://mysqlconnector.net/overview/installing/) in order to use it. It is supported in version 0.62.0 and later.
+Note: This API is a unique feature of MySqlConnector; you must [switch to MySqlConnector](https://mysqlconnector.net/overview/installing/) in order to use it.
+
+This API is experimental and may change in the future.
 
 ## See Also
 
diff --git a/docs/content/api/MySqlConnector/MySqlConnection/GetSchemaAsync.md b/docs/content/api/MySqlConnector/MySqlConnection/GetSchemaAsync.md
@@ -19,6 +19,10 @@ public Task<DataTable> GetSchemaAsync(
 
 A Task containing schema information.
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlConnection](../../MySqlConnectionType/)
@@ -45,6 +49,10 @@ public Task<DataTable> GetSchemaAsync(string collectionName,
 
 A Task containing schema information.
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlConnection](../../MySqlConnectionType/)
@@ -72,6 +80,10 @@ public Task<DataTable> GetSchemaAsync(string collectionName, string[] restrictio
 
 A Task containing schema information.
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlConnection](../../MySqlConnectionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/Release.md b/docs/content/api/MySqlConnector/MySqlTransaction/Release.md
@@ -14,6 +14,10 @@ public void Release(string savepointName)
 | --- | --- |
 | savepointName | The savepoint name. |
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/ReleaseAsync.md b/docs/content/api/MySqlConnector/MySqlTransaction/ReleaseAsync.md
@@ -20,6 +20,10 @@ public Task ReleaseAsync(string savepointName,
 
 A Task representing the asynchronous operation.
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/Rollback.md b/docs/content/api/MySqlConnector/MySqlTransaction/Rollback.md
@@ -32,6 +32,8 @@ public void Rollback(string savepointName)
 
 The name must have been created with [`Save`](../Save/), but not released by calling [`Release`](../Release/).
 
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/RollbackAsync.md b/docs/content/api/MySqlConnector/MySqlTransaction/RollbackAsync.md
@@ -18,7 +18,7 @@ public override Task RollbackAsync(CancellationToken cancellationToken = default
 
 # MySqlTransaction.RollbackAsync method (2 of 2)
 
-Asynchronously olls back the current transaction to the savepoint with the specified *savepointName* without aborting the transaction.
+Asynchronously rolls back the current transaction to the savepoint with the specified *savepointName* without aborting the transaction.
 
 ```csharp
 public Task RollbackAsync(string savepointName, 
@@ -38,6 +38,8 @@ A Task representing the asynchronous operation.
 
 The name must have been created with [`SaveAsync`](../SaveAsync/), but not released by calling [`ReleaseAsync`](../ReleaseAsync/).
 
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/Save.md b/docs/content/api/MySqlConnector/MySqlTransaction/Save.md
@@ -14,6 +14,10 @@ public void Save(string savepointName)
 | --- | --- |
 | savepointName | The savepoint name. |
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransaction/SaveAsync.md b/docs/content/api/MySqlConnector/MySqlTransaction/SaveAsync.md
@@ -20,6 +20,10 @@ public Task SaveAsync(string savepointName,
 
 A Task representing the asynchronous operation.
 
+## Remarks
+
+The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.
+
 ## See Also
 
 * class [MySqlTransaction](../../MySqlTransactionType/)
diff --git a/docs/content/api/MySqlConnector/MySqlTransactionType.md b/docs/content/api/MySqlConnector/MySqlTransactionType.md
@@ -22,7 +22,7 @@ public sealed class MySqlTransaction : DbTransaction
 | override [Rollback](../MySqlTransaction/Rollback/)() |  |
 | [Rollback](../MySqlTransaction/Rollback/)(…) | Rolls back the current transaction to the savepoint with the specified *savepointName* without aborting the transaction. |
 | override [RollbackAsync](../MySqlTransaction/RollbackAsync/)(…) |  |
-| [RollbackAsync](../MySqlTransaction/RollbackAsync/)(…) | Asynchronously olls back the current transaction to the savepoint with the specified *savepointName* without aborting the transaction. |
+| [RollbackAsync](../MySqlTransaction/RollbackAsync/)(…) | Asynchronously rolls back the current transaction to the savepoint with the specified *savepointName* without aborting the transaction. |
 | [Save](../MySqlTransaction/Save/)(…) | Sets a named transaction savepoint with the specified *savepointName*. If the current transaction already has a savepoint with the same name, the old savepoint is deleted and a new one is set. |
 | [SaveAsync](../MySqlTransaction/SaveAsync/)(…) | Asynchronously sets a named transaction savepoint with the specified *savepointName*. If the current transaction already has a savepoint with the same name, the old savepoint is deleted and a new one is set. |
 
diff --git a/src/MySqlConnector/MySqlBatch.cs b/src/MySqlConnector/MySqlBatch.cs
@@ -52,6 +52,7 @@ namespace MySqlConnector
 	///  await batch.ExecuteNonQueryAsync();
 	/// </code>
 	/// </summary>
+	/// <remarks>The proposed ADO.NET API that <see cref="MySqlBatch"/> is based on is not finalized. This API is experimental and may change in the future.</remarks>
 	public sealed class MySqlBatch : ICancellableCommand, IDisposable
 	{
 		/// <summary>
diff --git a/src/MySqlConnector/MySqlBulkCopy.cs b/src/MySqlConnector/MySqlBulkCopy.cs
@@ -37,8 +37,9 @@ namespace MySqlConnector
 	/// </code>
 	/// </summary>
 	/// <remarks><para><strong>Note:</strong> This API is a unique feature of MySqlConnector; you must
-	/// <a href="https://mysqlconnector.net/overview/installing/">switch to MySqlConnector</a> in order to use it.
-	/// It is supported in version 0.62.0 and later.</para></remarks>
+	/// <a href="https://mysqlconnector.net/overview/installing/">switch to MySqlConnector</a> in order to use it.</para>
+	/// <para>This API is experimental and may change in the future.</para>
+	/// </remarks>
 	public sealed class MySqlBulkCopy
 	{
 		/// <summary>
diff --git a/src/MySqlConnector/MySqlConnection.cs b/src/MySqlConnector/MySqlConnection.cs
@@ -539,6 +539,7 @@ private static async Task ClearPoolAsync(MySqlConnection connection, IOBehavior
 		/// </summary>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task{DataTable}"/> containing schema information.</returns>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public Task<DataTable> GetSchemaAsync(CancellationToken cancellationToken = default) => GetSchemaProvider().GetSchemaAsync(AsyncIOBehavior, cancellationToken).AsTask();
 
 		/// <summary>
@@ -547,6 +548,7 @@ private static async Task ClearPoolAsync(MySqlConnection connection, IOBehavior
 		/// <param name="collectionName">The name of the schema to return.</param>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task{DataTable}"/> containing schema information.</returns>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public Task<DataTable> GetSchemaAsync(string collectionName, CancellationToken cancellationToken = default) => GetSchemaProvider().GetSchemaAsync(AsyncIOBehavior, collectionName, cancellationToken).AsTask();
 
 		/// <summary>
@@ -556,6 +558,7 @@ private static async Task ClearPoolAsync(MySqlConnection connection, IOBehavior
 		/// <param name="restrictions">The restrictions to apply to the schema; this parameter is currently ignored.</param>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task{DataTable}"/> containing schema information.</returns>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public Task<DataTable> GetSchemaAsync(string collectionName, string?[] restrictions, CancellationToken cancellationToken = default) => GetSchemaProvider().GetSchemaAsync(AsyncIOBehavior, collectionName, cancellationToken).AsTask();
 
 		private SchemaProvider GetSchemaProvider() => m_schemaProvider ??= new(this);
diff --git a/src/MySqlConnector/MySqlTransaction.cs b/src/MySqlConnector/MySqlTransaction.cs
@@ -48,6 +48,7 @@ private async Task RollbackAsync(IOBehavior ioBehavior, CancellationToken cancel
 		/// Removes the named transaction savepoint with the specified <paramref name="savepointName"/>. No commit or rollback occurs.
 		/// </summary>
 		/// <param name="savepointName">The savepoint name.</param>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public void Release(string savepointName) => ExecuteSavepointAsync("release ", savepointName, IOBehavior.Synchronous, default).GetAwaiter().GetResult();
 
 		/// <summary>
@@ -56,29 +57,33 @@ private async Task RollbackAsync(IOBehavior ioBehavior, CancellationToken cancel
 		/// <param name="savepointName">The savepoint name.</param>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public Task ReleaseAsync(string savepointName, CancellationToken cancellationToken = default) => ExecuteSavepointAsync("release ", savepointName, Connection?.AsyncIOBehavior ?? IOBehavior.Asynchronous, cancellationToken);
 
 		/// <summary>
 		/// Rolls back the current transaction to the savepoint with the specified <paramref name="savepointName"/> without aborting the transaction.
 		/// </summary>
 		/// <param name="savepointName">The savepoint name.</param>
-		/// <remarks>The name must have been created with <see cref="Save"/>, but not released by calling <see cref="Release"/>.</remarks>
+		/// <remarks><para>The name must have been created with <see cref="Save"/>, but not released by calling <see cref="Release"/>.</para>
+		/// <para>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</para></remarks>
 		public void Rollback(string savepointName) => ExecuteSavepointAsync("rollback to ", savepointName, IOBehavior.Synchronous, default).GetAwaiter().GetResult();
 
 		/// <summary>
-		/// Asynchronously olls back the current transaction to the savepoint with the specified <paramref name="savepointName"/> without aborting the transaction.
+		/// Asynchronously rolls back the current transaction to the savepoint with the specified <paramref name="savepointName"/> without aborting the transaction.
 		/// </summary>
 		/// <param name="savepointName">The savepoint name.</param>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
-		/// <remarks>The name must have been created with <see cref="SaveAsync"/>, but not released by calling <see cref="ReleaseAsync"/>.</remarks>
+		/// <remarks><para>The name must have been created with <see cref="SaveAsync"/>, but not released by calling <see cref="ReleaseAsync"/>.</para>
+		/// <para>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</para></remarks>
 		public Task RollbackAsync(string savepointName, CancellationToken cancellationToken = default) => ExecuteSavepointAsync("rollback to ", savepointName, Connection?.AsyncIOBehavior ?? IOBehavior.Asynchronous, cancellationToken);
 
 		/// <summary>
 		/// Sets a named transaction savepoint with the specified <paramref name="savepointName"/>. If the current transaction
 		/// already has a savepoint with the same name, the old savepoint is deleted and a new one is set.
 		/// </summary>
 		/// <param name="savepointName">The savepoint name.</param>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public void Save(string savepointName) => ExecuteSavepointAsync("", savepointName, IOBehavior.Synchronous, default).GetAwaiter().GetResult();
 
 		/// <summary>
@@ -88,6 +93,7 @@ private async Task RollbackAsync(IOBehavior ioBehavior, CancellationToken cancel
 		/// <param name="savepointName">The savepoint name.</param>
 		/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
 		/// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+		/// <remarks>The proposed ADO.NET API that this is based on is not finalized; this API may change in the future.</remarks>
 		public Task SaveAsync(string savepointName, CancellationToken cancellationToken = default) => ExecuteSavepointAsync("", savepointName, Connection?.AsyncIOBehavior ?? IOBehavior.Asynchronous, cancellationToken);
 
 		private async Task ExecuteSavepointAsync(string command, string savepointName, IOBehavior ioBehavior, CancellationToken cancellationToken)
