Skip to content

Commit 32f8514

Browse files
author
Ron Petrusha
authored
Restored enumeration member remarks, Part 7 (dotnet#2595)
* Added more enumeration member remarks * fix build issues * fix build issue * fix build issues * fix build issue * Apply suggestions from code review Co-Authored-By: Maira Wenzel <[email protected]> * Apply suggestions from code review Co-Authored-By: Maira Wenzel <[email protected]> * Incorporated review comments
1 parent 90de2b6 commit 32f8514

File tree

15 files changed

+198
-509
lines changed

15 files changed

+198
-509
lines changed

‎xml/System.Runtime.ConstrainedExecution/Consistency.xml‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -177,17 +177,7 @@
177177
</ReturnValue>
178178
<MemberValue>3</MemberValue>
179179
<Docs>
180-
<summary>In the face of exceptional conditions, the method is guaranteed not to corrupt state.</summary>
181-
<remarks>
182-
<format type="text/markdown"><![CDATA[
183-
184-
## Remarks
185-
186-
> [!NOTE]
187-
> This does not guarantee that the method will never fail; however, it does guarantee that such a failure will never corrupt state.
188-
189-
]]></format>
190-
</remarks>
180+
<summary>In the face of exceptional conditions, the method is guaranteed not to corrupt state. (This does not guarantee that the method will never fail; however, it does guarantee that such a failure will never corrupt state.)</summary>
191181
</Docs>
192182
</Member>
193183
</Members>

‎xml/System.Runtime.InteropServices/ClassInterfaceType.xml‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -106,15 +106,8 @@
106106
</ReturnValue>
107107
<MemberValue>1</MemberValue>
108108
<Docs>
109-
<summary>Indicates that the class only supports late binding for COM clients. A <see langword="dispinterface" /> for the class is automatically exposed to COM clients on request. The type library produced by [Tlbexp.exe (Type Library Exporter)](~/docs/framework/tools/tlbexp-exe-type-library-exporter.md) does not contain type information for the <see langword="dispinterface" /> in order to prevent clients from caching the DISPIDs of the interface. The <see langword="dispinterface" /> does not exhibit the versioning problems described in <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" /> because clients can only late-bind to the interface.</summary>
110-
<remarks>
111-
<format type="text/markdown"><![CDATA[
112-
113-
## Remarks
114-
This is the default setting for <xref:System.Runtime.InteropServices.ClassInterfaceAttribute>.
115-
116-
]]></format>
117-
</remarks>
109+
<summary><para>Indicates that the class only supports late binding for COM clients. A <see langword="dispinterface" /> for the class is automatically exposed to COM clients on request. The type library produced by <see href="~/docs/framework/tools/tlbexp-exe-type-library-exporter.md">Tlbexp.exe (Type Library Exporter)</see> does not contain type information for the <see langword="dispinterface" /> in order to prevent clients from caching the DISPIDs of the interface. The <see langword="dispinterface" /> does not exhibit the versioning problems described in <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" /> because clients can only late-bind to the interface.</para>
110+
<para>This is the default setting for <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" />. </para></summary>
118111
</Docs>
119112
</Member>
120113
<Member MemberName="AutoDual">
@@ -213,4 +206,4 @@
213206
</Docs>
214207
</Member>
215208
</Members>
216-
</Type>
209+
</Type>

‎xml/System.Runtime.Remoting.Metadata/SoapOption.xml‎

Lines changed: 39 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,44 @@
3131
<remarks>
3232
<format type="text/markdown"><![CDATA[
3333
34-
## Remarks
35-
The <xref:System.Runtime.Remoting.Metadata.SoapOption> enumeration is used to specify instructions to the .NET Framework on how it will generate the SOAP.
34+
## Remarks
35+
36+
The `SoapOption` enumeration is used to specify instructions to the .NET Framework on how it will generate the SOAP.
37+
38+
For example, while a class by default (with the `SoapOptions.None` enumeration value) might be remoted in the SOAP format as:
3639
40+
```xml
41+
<member1>10</member1>
42+
<member2 id="ref-3">hello</member2>
43+
<member3 href="#ref-3"/>
44+
<member4 href="#ref-4"/>
45+
<member4shared href="#ref-4"/>
46+
<member5 href="#ref-5"/>
47+
<member6 id="ref-6" xsi:type="SOAP-ENC:string">Hello World</member6>
48+
<str1 id="ref-7">hello &#60; world</str1>
49+
<str2 id="ref-8">&#60;</str2>
50+
<str3 id="ref-9">&#60; world</str3>
51+
<str4 href="#ref-7"/>
52+
```
53+
54+
Remoting serialization with the `SoapOptions.XsdString` option produces the following XML:
55+
56+
```xml
57+
<member1 xsi:type="xsd:int">10</member1>
58+
<member2 xsi:type="xsd:string">hello</member2>
59+
<member3 xsi:type="xsd:string">hello</member3>
60+
<member4 href="#ref-3"/>
61+
<member4shared href="#ref-3"/>
62+
<member5 href="#ref-4"/>
63+
<member6 xsi:type="xsd:string">Hello World</member6>
64+
<str1 xsi:type="xsd:string">hello &#60; world</str1>
65+
<str2 xsi:type="xsd:string">&#60;</str2>
66+
<str3 xsi:type="xsd:string">&#60; world</str3>
67+
<str4 xsi:type="xsd:string">hello &#60; world</str4>
68+
```
69+
70+
For more information about SOAP envelopes, see [www.w3.org/tr/soap/#_Toc478383494](https://www.w3.org/TR/soap/#_Toc478383494).
71+
3772
]]></format>
3873
</remarks>
3974
<forInternalUseOnly />
@@ -179,49 +214,9 @@
179214
</ReturnValue>
180215
<MemberValue>2</MemberValue>
181216
<Docs>
182-
<summary>Indicates that the output SOAP string type in a SOAP Envelope is using the <see langword="XSD" /> prefix, and that the resulting XML does not have an ID attribute for the string.</summary>
183-
<remarks>
184-
<format type="text/markdown"><![CDATA[
185-
186-
## Remarks
187-
For example, while a class by default might be remoted in the SOAP format as
188-
189-
```
190-
<member1>10</member1>
191-
<member2 id="ref-3">hello</member2>
192-
<member3 href="#ref-3"/>
193-
<member4 href="#ref-4"/>
194-
<member4shared href="#ref-4"/>
195-
<member5 href="#ref-5"/>
196-
<member6 id="ref-6" xsi:type="SOAP-ENC:string">Hello World</member6>
197-
<str1 id="ref-7">hello &#60; world</str1>
198-
<str2 id="ref-8">&#60;</str2>
199-
<str3 id="ref-9">&#60; world</str3>
200-
<str4 href="#ref-7"/>
201-
```
202-
203-
remoting serialization with the `XsdString` option would produce the following XML.
204-
205-
```
206-
<member1 xsi:type="xsd:int">10</member1>
207-
<member2 xsi:type="xsd:string">hello</member2>
208-
<member3 xsi:type="xsd:string">hello</member3>
209-
<member4 href="#ref-3"/>
210-
<member4shared href="#ref-3"/>
211-
<member5 href="#ref-4"/>
212-
<member6 xsi:type="xsd:string">Hello World</member6>
213-
<str1 xsi:type="xsd:string">hello &#60; world</str1>
214-
<str2 xsi:type="xsd:string">&#60;</str2>
215-
<str3 xsi:type="xsd:string">&#60; world</str3>
216-
<str4 xsi:type="xsd:string">hello &#60; world</str4>
217-
```
218-
219-
For more information about SOAP envelopes, see www.w3.org/tr/soap/#_Toc478383494.
220-
221-
]]></format>
222-
</remarks>
217+
<summary>Indicates that the output SOAP string type in a SOAP Envelope uses the <see langword="XSD" /> prefix, and that the resulting XML does not have an ID attribute for the string.</summary>
223218
<forInternalUseOnly />
224219
</Docs>
225220
</Member>
226221
</Members>
227-
</Type>
222+
</Type>

‎xml/System.Security.Cryptography.X509Certificates/StoreLocation.xml‎

Lines changed: 10 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -31,17 +31,19 @@
3131
<remarks>
3232
<format type="text/markdown"><![CDATA[
3333
34-
## Remarks
35-
This enumeration is used with the <xref:System.Security.Cryptography.X509Certificates.X509Store> constructor.
34+
## Remarks
35+
36+
This enumeration is used with the <xref:System.Security.Cryptography.X509Certificates.X509Store> constructor.
3637
3738
3839
39-
## Examples
40-
The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.
41-
42-
[!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
43-
[!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
44-
[!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]
40+
## Examples
41+
42+
The following example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.
43+
44+
[!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
45+
[!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
46+
[!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]
4547
4648
]]></format>
4749
</remarks>
@@ -79,18 +81,6 @@
7981
<MemberValue>1</MemberValue>
8082
<Docs>
8183
<summary>The X.509 certificate store used by the current user.</summary>
82-
<remarks>
83-
<format type="text/markdown"><![CDATA[
84-
85-
## Examples
86-
The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.
87-
88-
[!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
89-
[!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
90-
[!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]
91-
92-
]]></format>
93-
</remarks>
9484
</Docs>
9585
</Member>
9686
<Member MemberName="LocalMachine">
@@ -125,18 +115,6 @@
125115
<MemberValue>2</MemberValue>
126116
<Docs>
127117
<summary>The X.509 certificate store assigned to the local machine.</summary>
128-
<remarks>
129-
<format type="text/markdown"><![CDATA[
130-
131-
## Examples
132-
The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.
133-
134-
[!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
135-
[!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
136-
[!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]
137-
138-
]]></format>
139-
</remarks>
140118
</Docs>
141119
</Member>
142120
</Members>

‎xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml‎

Lines changed: 6 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@
2424
<format type="text/markdown"><![CDATA[
2525
2626
## Remarks
27-
The <xref:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction> enumeration defines the type of algorithm that will be used to transform a raw secret agreement into key material. The secret agreement is the value that is generated from a private key and the other party's public key, as part of the key exchange. It is the seed value for the key material that is generated by the <xref:System.Security.Cryptography.ECDiffieHellmanCng.DeriveKeyMaterial%2A> method.
27+
The `ECDiffieHellmanKeyDerivationFunction` enumeration defines the type of algorithm that will be used to transform a raw secret agreement into key material. The secret agreement is the value that is generated from a private key and the other party's public key, as part of the key exchange. It is the seed value for the key material that is generated by the <xref:System.Security.Cryptography.ECDiffieHellmanCng.DeriveKeyMaterial%2A?displayProperty=nameWithType> method.
2828
29-
The <xref:System.Security.Cryptography.ECDiffieHellmanCng.KeyDerivationFunction%2A> property uses this enumeration to get the key derivation function for the <xref:System.Security.Cryptography.ECDiffieHellmanCng> class.
29+
The <xref:System.Security.Cryptography.ECDiffieHellmanCng.KeyDerivationFunction%2A?displayProperty=nameWithType> property uses this enumeration to get the key derivation function for the <xref:System.Security.Cryptography.ECDiffieHellmanCng> class.
3030
3131
]]></format>
3232
</remarks>
@@ -55,17 +55,7 @@
5555
</ReturnValue>
5656
<MemberValue>0</MemberValue>
5757
<Docs>
58-
<summary>A hash algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HashAlgorithm" /> property specifies the name of the algorithm to use. If the algorithm name is not specified, <see cref="T:System.Security.Cryptography.SHA256" /> is used as the default algorithm.</summary>
59-
<remarks>
60-
<format type="text/markdown"><![CDATA[
61-
62-
## Remarks
63-
You can also specify the <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend%2A> and <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend%2A> properties, but they are not required.
64-
65-
The amount of key material that is generated is equivalent to the size of the hash value for the specified algorithm.
66-
67-
]]></format>
68-
</remarks>
58+
<summary>A hash algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HashAlgorithm" /> property specifies the name of the algorithm to use. If the algorithm name is not specified, <see cref="T:System.Security.Cryptography.SHA256" /> is used as the default algorithm. You can also specify the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend" /> properties, but they are not required. The amount of key material that is generated is equivalent to the size of the hash value for the specified algorithm.</summary>
6959
</Docs>
7060
</Member>
7161
<Member MemberName="Hmac">
@@ -91,17 +81,7 @@
9181
</ReturnValue>
9282
<MemberValue>1</MemberValue>
9383
<Docs>
94-
<summary>A Hash-based Message Authentication Code (HMAC) algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HmacKey" /> property specifies the key to use. Either this property must be set or the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.UseSecretAgreementAsHmacKey" /> property must be set to <see langword="true" />; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Hmac" />. If both properties are set, the secret agreement is used as the HMAC key.</summary>
95-
<remarks>
96-
<format type="text/markdown"><![CDATA[
97-
98-
## Remarks
99-
You can also specify the <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend%2A> and <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend%2A> properties, but they are not required.
100-
101-
The amount of key material that is generated is equivalent to the size of the HMAC value.
102-
103-
]]></format>
104-
</remarks>
84+
<summary>A Hash-based Message Authentication Code (HMAC) algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HmacKey" /> property specifies the key to use. Either this property must be set or the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.UseSecretAgreementAsHmacKey" /> property must be set to <see langword="true" />; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Hmac" />. If both properties are set, the secret agreement is used as the HMAC key. You can also specify the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend" /> properties, but they are not required. The amount of key material that is generated is equivalent to the size of the HMAC value.</summary>
10585
</Docs>
10686
</Member>
10787
<Member MemberName="Tls">
@@ -127,16 +107,8 @@
127107
</ReturnValue>
128108
<MemberValue>2</MemberValue>
129109
<Docs>
130-
<summary>The Transport Layer Security (TLS) protocol is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Seed" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Label" /> properties must be set; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Tls" />.</summary>
131-
<remarks>
132-
<format type="text/markdown"><![CDATA[
133-
134-
## Remarks
135-
This value generates 160 bits of key material.
136-
137-
]]></format>
138-
</remarks>
110+
<summary>The Transport Layer Security (TLS) protocol is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Seed" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Label" /> properties must be set; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Tls" />. This value generates 160 bits of key material.</summary>
139111
</Docs>
140112
</Member>
141113
</Members>
142-
</Type>
114+
</Type>

‎xml/System.Security.Cryptography/KeyNumber.xml‎

Lines changed: 3 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,7 @@
3939
<format type="text/markdown"><![CDATA[
4040
4141
## Remarks
42-
Use the <xref:System.Security.Cryptography.KeyNumber> enumeration with the <xref:System.Security.Cryptography.CspKeyContainerInfo.KeyNumber%2A> property to inspect a key type or with the <xref:System.Security.Cryptography.CspParameters.KeyNumber> field to specify a key type.
43-
44-
42+
Use the `KeyNumber` enumeration with the <xref:System.Security.Cryptography.CspKeyContainerInfo.KeyNumber%2A?displayProperty=nameWithType> property to inspect a key type or with the <xref:System.Security.Cryptography.CspParameters.KeyNumber?displayProperty=nameWithType> field to specify a key type.
4543
4644
## Examples
4745
The following code example demonstrates how to use the <xref:System.Security.Cryptography.KeyNumber> enumeration to specify a key type for an <xref:System.Security.Cryptography.RSACryptoServiceProvider> object.
@@ -84,15 +82,7 @@
8482
</ReturnValue>
8583
<MemberValue>1</MemberValue>
8684
<Docs>
87-
<summary>An exchange key pair used to encrypt session keys so that they can be safely stored and exchanged with other users.</summary>
88-
<remarks>
89-
<format type="text/markdown"><![CDATA[
90-
91-
## Remarks
92-
This value corresponds to the AT_KEYEXCHANGE value used in the unmanaged Microsoft Cryptographic API (CAPI).
93-
94-
]]></format>
95-
</remarks>
85+
<summary>An exchange key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. This value corresponds to the AT_KEYEXCHANGE value used in the unmanaged Microsoft Cryptographic API (CAPI).</summary>
9686
</Docs>
9787
</Member>
9888
<Member MemberName="Signature">
@@ -125,15 +115,7 @@
125115
</ReturnValue>
126116
<MemberValue>2</MemberValue>
127117
<Docs>
128-
<summary>A signature key pair used for authenticating digitally signed messages or files.</summary>
129-
<remarks>
130-
<format type="text/markdown"><![CDATA[
131-
132-
## Remarks
133-
This value corresponds to the AT_SIGNATURE value used in the unmanaged Microsoft Cryptographic API (CAPI).
134-
135-
]]></format>
136-
</remarks>
118+
<summary>A signature key pair used for authenticating digitally signed messages or files. This value corresponds to the AT_SIGNATURE value used in the unmanaged Microsoft Cryptographic API (CAPI).</summary>
137119
</Docs>
138120
</Member>
139121
</Members>

0 commit comments

Comments
 (0)