Skip to content

XML Documentation Fixes - Batch 7 #2869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benrr101 merged 3 commits into from
Sep 23, 2024
Merged

XML Documentation Fixes - Batch 7 #2869

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
930846c
Batch 7 w/o testing
benrr101 Sep 17, 2024
58202f1
Spot checking!
benrr101 Sep 17, 2024
eab151e
Fixing build issue
benrr101 Sep 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 86 additions & 56 deletions doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml
View file
Open in desktop
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
Open in desktop
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