Skip to content

Commit

Permalink
XML Documentation Fixes - Batch 7 (#2869)
Browse files Browse the repository at this point in the history 
* Batch 7 w/o testing

* Spot checking!

* Fixing build issue
  • Loading branch information
@benrr101
benrr101 authored Sep 23, 2024
1 parent 3d9c1e4 commit c690120
Show file tree
Hide file tree
Showing 10 changed files with 1,212 additions and 605 deletions.
142 changes: 86 additions & 56 deletions doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,87 @@
<?xml version="1.0"?>
<docs>
<members name="SqlRetryLogicBase">
<SqlRetryLogicBase>
<summary>Retrieves the next time interval with respect to the number of retries if a transient condition occurs.</summary>
</SqlRetryLogicBase>
<NumberOfTries>
<summary>Maximum number of retries.</summary>
<value>
<see langword="int" /> that returns the maximum number of retry execution attempts that will be attempted after the first failure.</value>
</NumberOfTries>
<Current>
<summary>Current retry number starting from zero.</summary>
<value>
<see langword="int" /> that returns the number of retry execution attempts after the first failure.</value>
</Current>
<RetryIntervalEnumerator>
<summary>The timer interval enumerator.</summary>
<value>
<see cref="T:Microsoft.Data.SqlClient.SqlRetryIntervalBaseEnumerator" /> value that indicates an enumerator to generate a sequence of time intervals.</value>
</RetryIntervalEnumerator>
<TransientPredicate>
<summary>Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens.</summary>
<value>
<see cref="T:System.Predicate`1" /> value that delegates to a function that receives a <see cref="T:System.Exception" /> input parameter.</value>
</TransientPredicate>
<RetryCondition>
<param name="sender">The sender object.</param>
<summary>Pre-retry validation for the sender state.</summary>
<returns>Returns <see langword="true"/> if the sender is authorized to retry the operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
> [IMPORTANT!]
> Operations that are part of a **Transaction** are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level.
> [!NOTE]
> The `RetryCondition` is an extra condition that checks before executing the `TransientPredicate` and the default condition always returns **true**.
]]></format>
</remarks>
</RetryCondition>
<TryNextInterval>
<param name="intervalTime">The interval time that is generated by the `RetryIntervalEnumerator`.</param>
<summary>Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries.</summary>
<returns>Returns <see langword='true'/> if the number of retry attempts has not been exceeded; otherwise <see langword='false'/>.</returns>
</TryNextInterval>
<Reset>
<summary>Set the counters and enumerator to default values for next use.</summary>
</Reset>
<Clone>
<summary>Creates a new object that is a copy of the current instance.</summary>
<returns>When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws NotImplementedException.</returns>
<exception cref="T:System.NotImplementedException" >In all cases.</exception>
</Clone>
</members>
<docs>
<members name="SqlRetryLogicBase">
<SqlRetryLogicBase>
<summary>
Retrieves the next time interval with respect to the number of retries if a transient condition occurs.
</summary>
</SqlRetryLogicBase>
<NumberOfTries>
<summary>
Maximum number of retries.
</summary>
<value>
<see langword="int" /> that returns the maximum number of retry execution attempts that will be attempted after the first failure.
</value>
</NumberOfTries>
<Current>
<summary>
Current retry number starting from zero.
</summary>
<value>
<see langword="int" /> that returns the number of retry execution attempts after the first failure.
</value>
</Current>
<RetryIntervalEnumerator>
<summary>
The timer interval enumerator.
</summary>
<value>
<see cref="T:Microsoft.Data.SqlClient.SqlRetryIntervalBaseEnumerator" /> value that indicates an enumerator to generate a sequence of time intervals.
</value>
</RetryIntervalEnumerator>
<TransientPredicate>
<summary>
Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens.
</summary>
<value>
<see cref="T:System.Predicate`1" /> value that delegates to a function that receives a <see cref="T:System.Exception" /> input parameter.
</value>
</TransientPredicate>
<RetryCondition>
<param name="sender">
The sender object.
</param>
<summary>
Pre-retry validation for the sender state.
</summary>
<returns>
Returns <see langword="true" /> if the sender is authorized to retry the operation.
</returns>
<remarks>
<note type="important">
Operations that are part of a <b>Transaction</b> are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level.
</note>
<note type="note">
The <b>RetryCondition</b> is an extra condition that checks before executing the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBase.TransientPredicate" /> and the default condition always returns <see langword="true" />.
</note>
</remarks>
</RetryCondition>
<TryNextInterval>
<param name="intervalTime">
The interval time that is generated by the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBase.RetryIntervalEnumerator" />.
</param>
<summary>
Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries.
</summary>
<returns>
Returns <see langword="true" /> if the number of retry attempts has not been exceeded; otherwise <see langword="false" />.
</returns>
</TryNextInterval>
<Reset>
<summary>
Set the counters and enumerator to default values for next use.
</summary>
</Reset>
<Clone>
<summary>
Creates a new object that is a copy of the current instance.
</summary>
<returns>
When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws <see cref="T:System.NotImplementedException" />.
</returns>
<exception cref="T:System.NotImplementedException">
In all cases.
</exception>
</Clone>
</members>
</docs>
224 changes: 135 additions & 89 deletions doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBaseProvider.xml
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,136 @@
<?xml version="1.0"?>
<docs>
<members name="SqlRetryLogicBaseProvider">
<SqlRetryLogicBaseProvider>
<summary>Applies retry logic on an operation through the `Execute` or `ExecuteAsync` function.</summary>
</SqlRetryLogicBaseProvider>
<Retrying>
<summary>Occurs before applying the calculated delay time and executing the function on a next attempt.</summary>
<value>
<see cref="System.EventHandler" /> with event argument of <see cref="T:Microsoft.Data.SqlClient.SqlRetryingEventArgs" /> object can be subscribed.</value>
<remarks>
<format type="text/markdown"><![CDATA[
> [IMPORTANT!]
> Don't block execution with a time consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread.
]]>
</format>
</remarks>
</Retrying>
<RetryLogic>
<summary>Defines the retry logic used to decide when to retry based on the encountered exception.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
> [!NOTE]
> The `RetryLogic` property is assigned at `SqlRetryLogicBaseProvider` creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the <xref=E:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Retrying> event to collect data about retry executions.
]]>
</format>
</remarks>
</RetryLogic>
<Execute>
<typeparam name = "TResult">The object that the `function` returns when executed.</typeparam>
<param name="sender">The source of the event.</param>
<param name="function">The operation to re-execute if a transient condition occurs.</param>
<summary>Executes a function and applies retry logic, if enabled. **Note:** Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts.
</summary>
<returns>The return value of the `function` if it runs without exception.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
> [!NOTE]
> The type of exception depends on the `function`'s internal implementation. But if the exception is due to all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions that happened during the failed attempts.
]]>
</format>
</remarks>
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
<exception cref="T:System.AggregateException">The collection of exceptions after all retry attempts have failed.</exception>
</Execute>
<ExecuteAsync1>
<typeparam name = "TResult">The object that the `function` returns in a Task when executed.</typeparam>
<param name="sender">The source of the event.</param>
<param name="function">The operation to re-execute if a transient condition occurs.</param>
<param name="cancellationToken">The cancellation instruction.</param>
<summary>Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.</summary>
<returns>A task representing the asynchronous operation. The results of the task will be the return value of the `function`, if it runs without exception.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
> [!NOTE]
> If the exception comes from all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions from the failed attempts.
]]>
</format>
</remarks>
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
<exception cref="T:System.AggregateException">The collection of exceptions after failed retry attempts.</exception>
</ExecuteAsync1>
<ExecuteAsync2>
<param name="sender">The source of the event.</param>
<param name="function">The operation to re-execute if a transient condition occurs.</param>
<param name="cancellationToken">The cancellation instruction.</param>
<summary>Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.</summary>
<returns>A Task or an exception.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
> [!NOTE]
> If the exception comes from all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions from the failed attempts.
]]>
</format>
</remarks>
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
<exception cref="T:System.AggregateException">The collection of exceptions after failed retry attempts.</exception>
</ExecuteAsync2>
</members>
<docs>
<members name="SqlRetryLogicBaseProvider">
<SqlRetryLogicBaseProvider>
<summary>
Applies retry logic on an operation through the <see cref="M:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute{TResult}(System.Object,System.Func{TResult})" /> or <see cref="M:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute{TResult}(System.Object,System.Func{System.Threading.Task{TResult}},System.Threading.CancellationToken)" /> function.
</summary>
</SqlRetryLogicBaseProvider>
<Retrying>
<summary>
Occurs before applying the calculated delay time and executing the function on a next attempt.
</summary>
<value>
<see cref="T:System.EventHandler" /> with event argument of <see cref="T:Microsoft.Data.SqlClient.SqlRetryingEventArgs" /> object can be subscribed.
</value>
<remarks>
<note type="important">
Don't block execution with a time-consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread.
</note>
</remarks>
</Retrying>
<RetryLogic>
<summary>
Defines the retry logic used to decide when to retry based on the encountered exception.
</summary>
<remarks>
<note type="note">
The <b>RetryLogic</b> property is assigned at construction of the <see cref="T:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider" /> creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Retrying" /> event to collect data about retry executions.
</note>
</remarks>
</RetryLogic>
<Execute>
<typeparam name="TResult">
The object that the `function` returns when executed.
</typeparam>
<param name="sender">
The source of the event.
</param>
<param name="function">
The operation to re-execute if a transient condition occurs.
</param>
<summary>
<para>
Executes a function and applies retry logic, if enabled.
</para>
<note type="note">
Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts.
</note>
</summary>
<returns>
The return value of the <paramref name="function" /> if it runs without exception.
</returns>
<remarks>
<para>
<note type="note">
The type of exception depends on the <paramref name="function" />'s internal implementation. But if the exception is due to all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions that happened during the failed attempts.
</note>
</para>
</remarks>
<exception cref="T:System.ArgumentNullException">
The <paramref name="function" /> parameter can't be <see langword="null" />.
</exception>
<exception cref="T:System.AggregateException">
The collection of exceptions after all retry attempts have failed.
</exception>
</Execute>
<ExecuteAsync1>
<typeparam name="TResult">
The object that the <paramref name="function" /> returns in a Task when executed.
</typeparam>
<param name="sender">
The source of the event.
</param>
<param name="function">
The operation to re-execute if a transient condition occurs.
</param>
<param name="cancellationToken">
The cancellation instruction.
</param>
<summary>
<para>
Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded.
</para>
<note type="note">
Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.
</note>
</summary>
<returns>
A task representing the asynchronous operation. The results of the task will be the return value of the <paramref name="function" />, if it runs without exception.
</returns>
<remarks>
<note type="note">
If the exception comes from all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions from the failed attempts.
</note>
</remarks>
<exception cref="T:System.ArgumentNullException">
The <paramref name="function" /> parameter can't be <see langword="null" />.
</exception>
<exception cref="T:System.AggregateException">
The collection of exceptions after failed retry attempts.
</exception>
</ExecuteAsync1>
<ExecuteAsync2>
<param name="sender">
The source of the event.
</param>
<param name="function">
The operation to re-execute if a transient condition occurs.
</param>
<param name="cancellationToken">
The cancellation instruction.
</param>
<summary>
<para>
Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded.
</para>
<note type="note">
Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.
</note>
</summary>
<returns>
A Task or an exception.
</returns>
<remarks>
<note type="note">
If the exception comes from all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions from the failed attempts.
</note>
</remarks>
<exception cref="T:System.ArgumentNullException">
The <paramref name="function" /> parameter can't be <see langword="null" />.
</exception>
<exception cref="T:System.AggregateException">
The collection of exceptions after failed retry attempts.
</exception>
</ExecuteAsync2>
</members>
</docs>
Loading

0 comments on commit c690120

Please sign in to comment.