Skip to content
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

XML Documentation Fixes - Batch 4 #2863

Merged
merged 4 commits into from
Sep 19, 2024
Merged

XML Documentation Fixes - Batch 4 #2863

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0dab784
Batch 4
benrr101 Sep 6, 2024
61ad475
Touching up and fixing mistakes
benrr101 Sep 12, 2024
7bb429d
Tabs to spaces
benrr101 Sep 12, 2024
ca25b5d
Using new sample file
benrr101 Sep 18, 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
967 changes: 529 additions & 438 deletions doc/snippets/Microsoft.Data.SqlClient/SqlCommandBuilder.xml
View file
Open in desktop

Large diffs are not rendered by default.

66 changes: 38 additions & 28 deletions doc/snippets/Microsoft.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,39 @@
<docs>
<members name="SqlCommandColumnEncryptionSetting">
<SqlCommandColumnEncryptionSetting>
<summary>Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see <see href="https://docs.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted (Database Engine)</see>.
</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
- If Always Encrypted is disabled for a query and the query has parameters that need to be encrypted (parameters that correspond to encrypted columns), the query will fail.
- If Always Encrypted is disabled for a query and the query returns results from encrypted columns, the query will return encrypted values. The encrypted values will have the varbinary datatype.

]]></format>
</remarks>
</SqlCommandColumnEncryptionSetting>
<Disabled>
<summary>Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.</summary>
</Disabled>
<Enabled>
<summary>Enables Always Encrypted for the query.</summary>
</Enabled>
<ResultSetOnly>
<summary>Specifies that only the results of the command should be processed by the Always Encrypted routine in the driver. Use this value when the command has no parameters that require encryption.</summary>
</ResultSetOnly>
<UseConnectionSetting>
<summary>Specifies that the command should default to the Always Encrypted setting in the connection string.</summary>
</UseConnectionSetting>
</members>
<docs>
<members name="SqlCommandColumnEncryptionSetting">
<SqlCommandColumnEncryptionSetting>
<summary>
Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see <see href="https://docs.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted (Database Engine)</see>.
</summary>
<remarks>
<list type="bullet">
<item>
If Always Encrypted is disabled for a query and the query has parameters that need to be encrypted (parameters that correspond to encrypted columns), the query will fail.
</item>
<item>
If Always Encrypted is disabled for a query and the query returns results from encrypted columns, the query will return encrypted values. The encrypted values will have the varbinary datatype.
</item>
</list>
</remarks>
</SqlCommandColumnEncryptionSetting>
<Disabled>
<summary>
Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.
</summary>
</Disabled>
<Enabled>
<summary>
Enables Always Encrypted for the query.
</summary>
</Enabled>
<ResultSetOnly>
<summary>
Specifies that only the results of the command should be processed by the Always Encrypted routine in the driver. Use this value when the command has no parameters that require encryption.
</summary>
</ResultSetOnly>
<UseConnectionSetting>
<summary>
Specifies that the command should default to the Always Encrypted setting in the connection string.
</summary>
</UseConnectionSetting>
</members>
</docs>
364 changes: 249 additions & 115 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConfigurableRetryFactory.xml
View file
Open in desktop

Large diffs are not rendered by default.

4,644 changes: 3,315 additions & 1,329 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml
View file
Open in desktop

Large diffs are not rendered by default.

64 changes: 40 additions & 24 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnectionAttestationProtocol.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,41 @@
<docs>
<members name="SqlConnectionAttestationProtocol">
<SqlConnectionAttestationProtocol>
<summary>
Specifies a value for Attestation Protocol.
</summary>
</SqlConnectionAttestationProtocol>
<NotSpecified>
<summary>If the attestation protocol is not specified. Use this as default value.</summary>
<value>0</value>
</NotSpecified>
<AAS>
<summary>Attestation portocol for Azure Attestation Service</summary>
<value>1</value>
</AAS>
<None>
<summary>Attestation protocol for no attestation. Only compatible with Virtualization-based security (VBS) enclaves. An Enclave Attestation Url is not required when using this protocol.</summary>
<value>2</value>
</None>
<HGS>
<summary>Attestation protocol for Host Guardian Service</summary>
<value>3</value>
</HGS>
</members>
<docs>
<members name="SqlConnectionAttestationProtocol">
<SqlConnectionAttestationProtocol>
<summary>
Specifies a value for Attestation Protocol.
</summary>
</SqlConnectionAttestationProtocol>
<NotSpecified>
<summary>
If the attestation protocol is not specified. Use this as default value.
</summary>
<value>
0
</value>
</NotSpecified>
<AAS>
<summary>
Attestation protocol for Azure Attestation Service
</summary>
<value>
1
</value>
</AAS>
<None>
<summary>
Attestation protocol for no attestation. Only compatible with Virtualization-based security (VBS) enclaves. An Enclave Attestation Url is not required when using this protocol.
</summary>
<value>
2
</value>
</None>
<HGS>
<summary>
Attestation protocol for Host Guardian Service
</summary>
<value>
3
</value>
</HGS>
</members>
</docs>
32 changes: 18 additions & 14 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
<?xml version="1.0"?>
<docs>
<members name="SqlConnectionColumnEncryptionSetting">
<SqlConnectionColumnEncryptionSetting>
<summary>Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see <see href="https://docs.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted (Database Engine)</see>.</summary>
<remarks>To be added.</remarks>
</SqlConnectionColumnEncryptionSetting>
<Disabled>
<summary>Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.</summary>
</Disabled>
<Enabled>
<summary>Enables Always Encrypted functionality for the connection. Query parameters that correspond to encrypted columns will be transparently encrypted and query results from encrypted columns will be transparently decrypted.</summary>
</Enabled>
</members>
<docs>
<members name="SqlConnectionColumnEncryptionSetting">
<SqlConnectionColumnEncryptionSetting>
<summary>
Note that these settings cannot be used to bypass encryption and gain access to plaintext data. For details, see <see href="https://docs.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted (Database Engine)</see>.
</summary>
</SqlConnectionColumnEncryptionSetting>
<Disabled>
<summary>
Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.
</summary>
</Disabled>
<Enabled>
<summary>
Enables Always Encrypted functionality for the connection. Query parameters that correspond to encrypted columns will be transparently encrypted and query results from encrypted columns will be transparently decrypted.
</summary>
</Enabled>
</members>
</docs>
62 changes: 38 additions & 24 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnectionEncryptOption.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,65 +1,79 @@
<?xml version="1.0"?>
<docs>
<docs>
<members name="SqlConnectionEncryptOption">
<SqlConnectionEncryptOption>
<summary>These options are used to control encryption behavior of the communication between the server and the client.</summary>
<summary>
These options are used to control encryption behavior of the communication between the server and the client.
</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Implicit conversions have been added to maintain backwards compatibility with boolean behavior for the <xref:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Encrypt%2A> property. When converting from a boolean, a value of `true` converts to <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory%2A> and a value of `false` converts to <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional%2A>. When converting to a boolean, <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory%2A>, <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Strict%2A> , and `null` convert to `true` and <xref:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional%2A> converts `false`.

]]></format>
Implicit conversions have been added to maintain backwards compatibility with boolean behavior for the <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.Encrypt" /> property. When converting from a boolean, a value of <see langword="true" /> converts to <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory" /> and a value of <see langword="false" /> converts to <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional" />. When converting to a boolean, <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory" />, <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Strict" />, and <see langword="null" /> convert to <see langword="true" /> and <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional" /> converts <see langword="false" />.
</remarks>
</SqlConnectionEncryptOption>
<Parse>
<summary>
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> equivalent.
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> equivalent.
</summary>
<param name="value">A string containing the value to convert.</param>
<param name="value">
A string containing the value to convert.
</param>
<returns>
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> contained in <paramref name="value"/>.
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> contained in <paramref name="value" />.
</returns>
<exception cref="T:System.ArgumentException">
Throws exception if provided <paramref name="value"/> is not convertible to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> type.
Throws exception if provided <paramref name="value" /> is not convertible to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> type.
</exception>
</Parse>
<TryParse>
<summary>
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> equivalent and returns a value that indicates whether the conversion succeeded.
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> equivalent and returns a value that indicates whether the conversion succeeded.
</summary>
<param name="value">A string containing the value to convert.</param>
<param name="value">
A string containing the value to convert.
</param>
<param name="result">
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> contained in <paramref name="value"/>. <see langword="null" /> if conversion fails.
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> contained in <paramref name="value" />. <see langword="null" /> if conversion fails.
</param>
<returns>
<see langword="true" /> if the <paramref name="value"/> parameter was converted successfully; otherwise, <see langword="false" />.
<see langword="true" /> if the <paramref name="value" /> parameter was converted successfully; otherwise, <see langword="false" />.
</returns>
<remarks>This method does not throw an exception if conversion fails.</remarks>
<remarks>
This method does not throw an exception if conversion fails.
</remarks>
</TryParse>
<Optional>
<summary>Specifies that TLS encryption is optional when connecting to the server. If the server requires encryption, encryption will be negotiated.</summary>
<summary>
Specifies that TLS encryption is optional when connecting to the server. If the server requires encryption, encryption will be negotiated.
</summary>
</Optional>
<Mandatory>
<summary>Specifies that TLS encryption is required when connecting to the server. If the server doesn't support encryption, the connection will fail.</summary>
<summary>
Specifies that TLS encryption is required when connecting to the server. If the server doesn't support encryption, the connection will fail.
</summary>
</Mandatory>
<Strict>
<summary>Enables and requires TDS 8.0, TLS encryption to the server. If the server doesn't support TDS 8.0, TLS encryption, the connection will fail.</summary>
<summary>
Enables and requires TDS 8.0, TLS encryption to the server. If the server doesn't support TDS 8.0, TLS encryption, the connection will fail.
</summary>
</Strict>
<BoolToOption>
<param name="value">The boolean value to be used for implicit comparison.</param>
<param name="value">
The boolean value to be used for implicit comparison.
</param>
<summary>
Enables implicit conversion of a boolean to a <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" />. A value of <see langword="true" /> converts to <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory" />. A value of <see langword="false" /> converts to <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional" />.
</summary>
</BoolToOption>
<OptionToBool>
<param name="value">The <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> value to be used for implicit comparison.</param>
<param name="value">
The <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> value to be used for implicit comparison.
</param>
<summary>
Enables implicit conversion of a <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> to a boolean. <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Mandatory" /> and <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Strict" /> convert to <see langword="true" />. <see cref="P:Microsoft.Data.SqlClient.SqlConnectionEncryptOption.Optional" /> converts to <see langword="false" />.
</summary>
</OptionToBool>
<ToString>
<summary>Returns the string value of <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" />.</summary>
<summary>
Returns the string value of <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" />.
</summary>
</ToString>
<Equals>
<summary>
Expand Down
76 changes: 37 additions & 39 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,38 @@
<docs>
<members name="SqlConnectionIPAddressPreference">
<SqlConnectionIPAddressPreferenceNetfx>
<summary>
Specifies a value for IP address preference during a TCP connection.
</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
If `Multi Subnet Failover` or "Transparent Network IP Resolution" is set to `true`, this setting has no effect.
]]></format>
</remarks>
</SqlConnectionIPAddressPreferenceNetfx>
<SqlConnectionIPAddressPreference>
<summary>
Specifies a value for IP address preference during a TCP connection.
</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
If `Multi Subnet Failover` is set to `true`, this setting has no effect.
]]></format>
</remarks>
</SqlConnectionIPAddressPreference>
<IPv4First>
<summary>Connects using IPv4 address(es) first. If the connection fails, try IPv6 address(es), if provided. This is the default value.</summary>
<value>0</value>
</IPv4First>
<IPv6First>
<summary>Connect using IPv6 address(es) first. If the connection fails, try IPv4 address(es), if available.</summary>
<value>1</value>
</IPv6First>
<UsePlatformDefault>
<summary>Connects with IP addresses in the order the underlying platform or operating system provides them.</summary>
<value>2</value>
</UsePlatformDefault>
</members>
<docs>
<members name="SqlConnectionIPAddressPreference">
<SqlConnectionIPAddressPreferenceNetfx>
<summary>
Specifies a value for IP address preference during a TCP connection.
</summary>
<remarks>
If <c>Multi Subnet Failover</c> or <c>Transparent Network IP Resolution</c> is set to <c>true</c>, this setting has no effect.
</remarks>
</SqlConnectionIPAddressPreferenceNetfx>
<SqlConnectionIPAddressPreference>
<summary>
Specifies a value for IP address preference during a TCP connection.
</summary>
<remarks>
If <c>Multi Subnet Failover</c> is set to <c>true</c>, this setting has no effect.
</remarks>
</SqlConnectionIPAddressPreference>
<IPv4First>
<summary>
Connects using IPv4 address(es) first. If the connection fails, try IPv6 address(es), if provided. This is the default value.
</summary>
<value>0</value>
</IPv4First>
<IPv6First>
<summary>
Connect using IPv6 address(es) first. If the connection fails, try IPv4 address(es), if available.
</summary>
<value>1</value>
</IPv6First>
<UsePlatformDefault>
<summary>
Connects with IP addresses in the order the underlying platform or operating system provides them.
</summary>
<value>2</value>
</UsePlatformDefault>
</members>
</docs>
40 changes: 24 additions & 16 deletions doc/snippets/Microsoft.Data.SqlClient/SqlConnectionOverrides.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,25 @@
<docs>
<members name="SqlConnectionOverrides">
<SqlConnectionOverrides>
<summary>
Specifies a value for Overrides.
</summary>
</SqlConnectionOverrides>
<None>
<summary>No overrides.</summary>
<value>0</value>
</None>
<OpenWithoutRetry>
<summary>Disable transient fault handling during the initial SqlConnection Open attempt.</summary>
<value>1</value>
</OpenWithoutRetry>
</members>
<docs>
<members name="SqlConnectionOverrides">
<SqlConnectionOverrides>
<summary>
Specifies a value for Overrides.
</summary>
</SqlConnectionOverrides>
<None>
<summary>
No overrides.
</summary>
<value>
0
</value>
</None>
<OpenWithoutRetry>
<summary>
Disable transient fault handling during the initial <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> <see cref="M:Microsoft.Data.SqlClient.SqlConnection.Open" /> attempt.
</summary>
<value>
1
</value>
</OpenWithoutRetry>
</members>
</docs>
Loading
Loading