Skip to content

Commit 3416ad9

Browse files
benrr101benrr101
authored
XML Documentation Fixes - Batch 4 (#2863)
* Batch 4 * Touching up and fixing mistakes * Tabs to spaces * Using new sample file
1 parent cdc33d9 commit 3416ad9

13 files changed

+4396
-2108
lines changed

‎doc/snippets/Microsoft.Data.SqlClient/SqlCommandBuilder.xml‎

Lines changed: 529 additions & 438 deletions
Large diffs are not rendered by default.

‎doc/snippets/Microsoft.Data.SqlClient/SqlCommandColumnEncryptionSetting.xml‎

Lines changed: 38 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,39 @@
1-
<docs>
2-
<members name="SqlCommandColumnEncryptionSetting">
3-
<SqlCommandColumnEncryptionSetting>
4-
<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>.
5-
</summary>
6-
<remarks>
7-
<format type="text/markdown"><![CDATA[
8-
9-
## Remarks
10-
- 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.
11-
- 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.
12-
13-
]]></format>
14-
</remarks>
15-
</SqlCommandColumnEncryptionSetting>
16-
<Disabled>
17-
<summary>Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.</summary>
18-
</Disabled>
19-
<Enabled>
20-
<summary>Enables Always Encrypted for the query.</summary>
21-
</Enabled>
22-
<ResultSetOnly>
23-
<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>
24-
</ResultSetOnly>
25-
<UseConnectionSetting>
26-
<summary>Specifies that the command should default to the Always Encrypted setting in the connection string.</summary>
27-
</UseConnectionSetting>
28-
</members>
1+
<docs>
2+
<members name="SqlCommandColumnEncryptionSetting">
3+
<SqlCommandColumnEncryptionSetting>
4+
<summary>
5+
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>.
6+
</summary>
7+
<remarks>
8+
<list type="bullet">
9+
<item>
10+
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.
11+
</item>
12+
<item>
13+
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.
14+
</item>
15+
</list>
16+
</remarks>
17+
</SqlCommandColumnEncryptionSetting>
18+
<Disabled>
19+
<summary>
20+
Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.
21+
</summary>
22+
</Disabled>
23+
<Enabled>
24+
<summary>
25+
Enables Always Encrypted for the query.
26+
</summary>
27+
</Enabled>
28+
<ResultSetOnly>
29+
<summary>
30+
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.
31+
</summary>
32+
</ResultSetOnly>
33+
<UseConnectionSetting>
34+
<summary>
35+
Specifies that the command should default to the Always Encrypted setting in the connection string.
36+
</summary>
37+
</UseConnectionSetting>
38+
</members>
2939
</docs>

‎doc/snippets/Microsoft.Data.SqlClient/SqlConfigurableRetryFactory.xml‎

Lines changed: 249 additions & 115 deletions
Large diffs are not rendered by default.

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml‎

Lines changed: 3325 additions & 1320 deletions
Large diffs are not rendered by default.

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnectionAttestationProtocol.xml‎

Lines changed: 40 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,41 @@
1-
<docs>
2-
<members name="SqlConnectionAttestationProtocol">
3-
<SqlConnectionAttestationProtocol>
4-
<summary>
5-
Specifies a value for Attestation Protocol.
6-
</summary>
7-
</SqlConnectionAttestationProtocol>
8-
<NotSpecified>
9-
<summary>If the attestation protocol is not specified. Use this as default value.</summary>
10-
<value>0</value>
11-
</NotSpecified>
12-
<AAS>
13-
<summary>Attestation portocol for Azure Attestation Service</summary>
14-
<value>1</value>
15-
</AAS>
16-
<None>
17-
<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>
18-
<value>2</value>
19-
</None>
20-
<HGS>
21-
<summary>Attestation protocol for Host Guardian Service</summary>
22-
<value>3</value>
23-
</HGS>
24-
</members>
1+
<docs>
2+
<members name="SqlConnectionAttestationProtocol">
3+
<SqlConnectionAttestationProtocol>
4+
<summary>
5+
Specifies a value for Attestation Protocol.
6+
</summary>
7+
</SqlConnectionAttestationProtocol>
8+
<NotSpecified>
9+
<summary>
10+
If the attestation protocol is not specified. Use this as default value.
11+
</summary>
12+
<value>
13+
0
14+
</value>
15+
</NotSpecified>
16+
<AAS>
17+
<summary>
18+
Attestation protocol for Azure Attestation Service
19+
</summary>
20+
<value>
21+
1
22+
</value>
23+
</AAS>
24+
<None>
25+
<summary>
26+
Attestation protocol for no attestation. Only compatible with Virtualization-based security (VBS) enclaves. An Enclave Attestation Url is not required when using this protocol.
27+
</summary>
28+
<value>
29+
2
30+
</value>
31+
</None>
32+
<HGS>
33+
<summary>
34+
Attestation protocol for Host Guardian Service
35+
</summary>
36+
<value>
37+
3
38+
</value>
39+
</HGS>
40+
</members>
2541
</docs>

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnectionColumnEncryptionSetting.xml‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
1-
<?xml version="1.0"?>
2-
<docs>
3-
<members name="SqlConnectionColumnEncryptionSetting">
4-
<SqlConnectionColumnEncryptionSetting>
5-
<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>
6-
<remarks>To be added.</remarks>
7-
</SqlConnectionColumnEncryptionSetting>
8-
<Disabled>
9-
<summary>Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.</summary>
10-
</Disabled>
11-
<Enabled>
12-
<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>
13-
</Enabled>
14-
</members>
1+
<docs>
2+
<members name="SqlConnectionColumnEncryptionSetting">
3+
<SqlConnectionColumnEncryptionSetting>
4+
<summary>
5+
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>.
6+
</summary>
7+
</SqlConnectionColumnEncryptionSetting>
8+
<Disabled>
9+
<summary>
10+
Specifies the connection does not use Always Encrypted. Should be used if no queries sent over the connection access encrypted columns.
11+
</summary>
12+
</Disabled>
13+
<Enabled>
14+
<summary>
15+
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.
16+
</summary>
17+
</Enabled>
18+
</members>
1519
</docs>

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnectionEncryptOption.xml‎

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,79 @@
1-
<?xml version="1.0"?>
2-
<docs>
1+
<docs>
32
<members name="SqlConnectionEncryptOption">
43
<SqlConnectionEncryptOption>
5-
<summary>These options are used to control encryption behavior of the communication between the server and the client.</summary>
4+
<summary>
5+
These options are used to control encryption behavior of the communication between the server and the client.
6+
</summary>
67
<remarks>
7-
<format type="text/markdown"><![CDATA[
8-
9-
## Remarks
10-
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`.
11-
12-
]]></format>
8+
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" />.
139
</remarks>
1410
</SqlConnectionEncryptOption>
1511
<Parse>
1612
<summary>
17-
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> equivalent.
13+
Converts the specified string representation of a logical value to its <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> equivalent.
1814
</summary>
19-
<param name="value">A string containing the value to convert.</param>
15+
<param name="value">
16+
A string containing the value to convert.
17+
</param>
2018
<returns>
21-
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> contained in <paramref name="value"/>.
19+
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> contained in <paramref name="value" />.
2220
</returns>
2321
<exception cref="T:System.ArgumentException">
24-
Throws exception if provided <paramref name="value"/> is not convertible to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> type.
22+
Throws exception if provided <paramref name="value" /> is not convertible to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> type.
2523
</exception>
2624
</Parse>
2725
<TryParse>
2826
<summary>
29-
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.
27+
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.
3028
</summary>
31-
<param name="value">A string containing the value to convert.</param>
29+
<param name="value">
30+
A string containing the value to convert.
31+
</param>
3232
<param name="result">
33-
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption"/> contained in <paramref name="value"/>. <see langword="null" /> if conversion fails.
33+
An object that is equivalent to <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> contained in <paramref name="value" />. <see langword="null" /> if conversion fails.
3434
</param>
3535
<returns>
36-
<see langword="true" /> if the <paramref name="value"/> parameter was converted successfully; otherwise, <see langword="false" />.
36+
<see langword="true" /> if the <paramref name="value" /> parameter was converted successfully; otherwise, <see langword="false" />.
3737
</returns>
38-
<remarks>This method does not throw an exception if conversion fails.</remarks>
38+
<remarks>
39+
This method does not throw an exception if conversion fails.
40+
</remarks>
3941
</TryParse>
4042
<Optional>
41-
<summary>Specifies that TLS encryption is optional when connecting to the server. If the server requires encryption, encryption will be negotiated.</summary>
43+
<summary>
44+
Specifies that TLS encryption is optional when connecting to the server. If the server requires encryption, encryption will be negotiated.
45+
</summary>
4246
</Optional>
4347
<Mandatory>
44-
<summary>Specifies that TLS encryption is required when connecting to the server. If the server doesn't support encryption, the connection will fail.</summary>
48+
<summary>
49+
Specifies that TLS encryption is required when connecting to the server. If the server doesn't support encryption, the connection will fail.
50+
</summary>
4551
</Mandatory>
4652
<Strict>
47-
<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>
53+
<summary>
54+
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.
55+
</summary>
4856
</Strict>
4957
<BoolToOption>
50-
<param name="value">The boolean value to be used for implicit comparison.</param>
58+
<param name="value">
59+
The boolean value to be used for implicit comparison.
60+
</param>
5161
<summary>
5262
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" />.
5363
</summary>
5464
</BoolToOption>
5565
<OptionToBool>
56-
<param name="value">The <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> value to be used for implicit comparison.</param>
66+
<param name="value">
67+
The <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" /> value to be used for implicit comparison.
68+
</param>
5769
<summary>
5870
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" />.
5971
</summary>
6072
</OptionToBool>
6173
<ToString>
62-
<summary>Returns the string value of <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" />.</summary>
74+
<summary>
75+
Returns the string value of <see cref="T:Microsoft.Data.SqlClient.SqlConnectionEncryptOption" />.
76+
</summary>
6377
</ToString>
6478
<Equals>
6579
<summary>

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml‎

Lines changed: 37 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,38 @@
1-
<docs>
2-
<members name="SqlConnectionIPAddressPreference">
3-
<SqlConnectionIPAddressPreferenceNetfx>
4-
<summary>
5-
Specifies a value for IP address preference during a TCP connection.
6-
</summary>
7-
<remarks>
8-
<format type="text/markdown"><![CDATA[
9-
10-
## Remarks
11-
If `Multi Subnet Failover` or "Transparent Network IP Resolution" is set to `true`, this setting has no effect.
12-
]]></format>
13-
</remarks>
14-
</SqlConnectionIPAddressPreferenceNetfx>
15-
<SqlConnectionIPAddressPreference>
16-
<summary>
17-
Specifies a value for IP address preference during a TCP connection.
18-
</summary>
19-
<remarks>
20-
<format type="text/markdown"><![CDATA[
21-
22-
## Remarks
23-
If `Multi Subnet Failover` is set to `true`, this setting has no effect.
24-
]]></format>
25-
</remarks>
26-
</SqlConnectionIPAddressPreference>
27-
<IPv4First>
28-
<summary>Connects using IPv4 address(es) first. If the connection fails, try IPv6 address(es), if provided. This is the default value.</summary>
29-
<value>0</value>
30-
</IPv4First>
31-
<IPv6First>
32-
<summary>Connect using IPv6 address(es) first. If the connection fails, try IPv4 address(es), if available.</summary>
33-
<value>1</value>
34-
</IPv6First>
35-
<UsePlatformDefault>
36-
<summary>Connects with IP addresses in the order the underlying platform or operating system provides them.</summary>
37-
<value>2</value>
38-
</UsePlatformDefault>
39-
</members>
1+
<docs>
2+
<members name="SqlConnectionIPAddressPreference">
3+
<SqlConnectionIPAddressPreferenceNetfx>
4+
<summary>
5+
Specifies a value for IP address preference during a TCP connection.
6+
</summary>
7+
<remarks>
8+
If <c>Multi Subnet Failover</c> or <c>Transparent Network IP Resolution</c> is set to <c>true</c>, this setting has no effect.
9+
</remarks>
10+
</SqlConnectionIPAddressPreferenceNetfx>
11+
<SqlConnectionIPAddressPreference>
12+
<summary>
13+
Specifies a value for IP address preference during a TCP connection.
14+
</summary>
15+
<remarks>
16+
If <c>Multi Subnet Failover</c> is set to <c>true</c>, this setting has no effect.
17+
</remarks>
18+
</SqlConnectionIPAddressPreference>
19+
<IPv4First>
20+
<summary>
21+
Connects using IPv4 address(es) first. If the connection fails, try IPv6 address(es), if provided. This is the default value.
22+
</summary>
23+
<value>0</value>
24+
</IPv4First>
25+
<IPv6First>
26+
<summary>
27+
Connect using IPv6 address(es) first. If the connection fails, try IPv4 address(es), if available.
28+
</summary>
29+
<value>1</value>
30+
</IPv6First>
31+
<UsePlatformDefault>
32+
<summary>
33+
Connects with IP addresses in the order the underlying platform or operating system provides them.
34+
</summary>
35+
<value>2</value>
36+
</UsePlatformDefault>
37+
</members>
4038
</docs>

‎doc/snippets/Microsoft.Data.SqlClient/SqlConnectionOverrides.xml‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,25 @@
1-
<docs>
2-
<members name="SqlConnectionOverrides">
3-
<SqlConnectionOverrides>
4-
<summary>
5-
Specifies a value for Overrides.
6-
</summary>
7-
</SqlConnectionOverrides>
8-
<None>
9-
<summary>No overrides.</summary>
10-
<value>0</value>
11-
</None>
12-
<OpenWithoutRetry>
13-
<summary>Disable transient fault handling during the initial SqlConnection Open attempt.</summary>
14-
<value>1</value>
15-
</OpenWithoutRetry>
16-
</members>
1+
<docs>
2+
<members name="SqlConnectionOverrides">
3+
<SqlConnectionOverrides>
4+
<summary>
5+
Specifies a value for Overrides.
6+
</summary>
7+
</SqlConnectionOverrides>
8+
<None>
9+
<summary>
10+
No overrides.
11+
</summary>
12+
<value>
13+
0
14+
</value>
15+
</None>
16+
<OpenWithoutRetry>
17+
<summary>
18+
Disable transient fault handling during the initial <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> <see cref="M:Microsoft.Data.SqlClient.SqlConnection.Open" /> attempt.
19+
</summary>
20+
<value>
21+
1
22+
</value>
23+
</OpenWithoutRetry>
24+
</members>
1725
</docs>

0 commit comments

Comments
 (0)