Skip to content

Commit e5fe7e6

Browse files
carlossanlopmairaw
carlossanlop
authored and
mairaw
committed
Automatically port comments for Microsoft.Win32, Numerics, Reflection, Runtime.CompilerServices, Runtime.InteropServices, Threading.Tasks (#2683)
* Automatically port isolated triple slash comments from various assemblies/namespaces * suggestions by mairaw Co-Authored-By: Maira Wenzel <[email protected]> * suggestions by mairaw * Suggestions * suggestion by maryamariyan * Corrected malformed XML * Fixed malformed XML * Update BigInteger.xml * Update MemberInfoExtensions.xml * Update SwitchExpressionException.xml * Update SequenceMarshal.xml * fix link text * fix formatting * Update ParallelOptions.xml * Update SequencePosition.xml * fix broken link
1 parent 44ad68a commit e5fe7e6

File tree

8 files changed

+167
-72
lines changed

8 files changed

+167
-72
lines changed

‎xml/Microsoft.Win32.SafeHandles/SafeNCryptHandle.xml

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,22 @@
3434
</Attributes>
3535
<Docs>
3636
<summary>Provides a safe handle that can be used by Cryptography Next Generation (CNG) objects.</summary>
37-
<remarks>To be added.</remarks>
37+
<remarks>
38+
<format type="text/markdown"><![CDATA[
39+
40+
## Remarks
41+
42+
43+
This class wraps up the logic to correctly duplicate and free these handles to simulate a native duplication.
44+
45+
Each open handle object can be thought of as being in one of three states:
46+
47+
- **Owner** - Created via the marshaler, traditional style safe handle. Notably, only one owner handle exists for a given native handle.
48+
- **Duplicate** - Points at a handle in the Holder state. Releasing a handle in the duplicate state results only in decrementing the reference count of the holder, not in a release of the native handle.
49+
- **Holder** - Holds onto a native handle and is referenced by handles in the duplicate state. When all duplicate handles are closed, the holder handle releases the native handle. A holder handle will never be finalized, since this results in a race between the finalizers of the duplicate handles and the holder handle. Instead, it relies upon all of the duplicate handles to be finalized and decrement the ref count to zero. Instances of a holder handle should never be referenced by anything but a duplicate handle.
50+
51+
]]></format>
52+
</remarks>
3853
<permission cref="T:System.Security.Permissions.SecurityPermission">for permission to call unmanaged code. Security action: <see cref="F:System.Security.Permissions.SecurityAction.InheritanceDemand" />. Associated enumeration: <see cref="F:System.Security.Permissions.SecurityPermissionFlag.UnmanagedCode" /></permission>
3954
<forInternalUseOnly />
4055
</Docs>
@@ -170,7 +185,21 @@
170185
<summary>Releases a handle used by a Cryptography Next Generation (CNG) object.</summary>
171186
<returns>
172187
<see langword="true" /> if the handle is released successfully; otherwise, <see langword="false" />.</returns>
173-
<remarks>To be added.</remarks>
188+
<remarks>
189+
<format type="text/markdown"><![CDATA[
190+
191+
## Remarks
192+
193+
Similar to duplication, releasing a handle performs different operations based upon the state of the handle.
194+
195+
An instance that was constructed with a parentHandle value will only call DangerousRelease on the parentHandle object. Otherwise, the behavior is dictated by the ownership state.
196+
197+
- **Owner** - Simply calls the release P/Invoke method.
198+
- **Duplicate** - Decrements the reference count of the current holder.
199+
- **Holder** - Calls the release P/Invoke. Note that ReleaseHandle on a holder implies a reference count of zero.
200+
201+
]]></format>
202+
</remarks>
174203
<forInternalUseOnly />
175204
</Docs>
176205
</Member>
@@ -217,4 +246,4 @@
217246
</Docs>
218247
</Member>
219248
</Members>
220-
</Type>
249+
</Type>

‎xml/System.Numerics/BigInteger.xml

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1545,9 +1545,9 @@
15451545
<Parameter Name="isUnsigned" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
15461546
</Parameters>
15471547
<Docs>
1548-
<param name="isUnsigned">To be added.</param>
1549-
<summary>To be added.</summary>
1550-
<returns>To be added.</returns>
1548+
<param name="isUnsigned"><see langword="true" /> to use unsigned encoding; otherwise, <see langword="false" />.</param>
1549+
<summary>Gets the number of bytes that will be output by <see cref="M:System.Numerics.BigInteger.ToByteArray(System.Boolean,System.Boolean)" /> and <see cref="M:System.Numerics.BigInteger.TryWriteBytes(System.Span{System.Byte},System.Int32@,System.Boolean,System.Boolean)" />.</summary>
1550+
<returns>The number of bytes.</returns>
15511551
<remarks>To be added.</remarks>
15521552
</Docs>
15531553
</Member>
@@ -7134,11 +7134,28 @@ value Mod 2 = 0
71347134
<Parameter Name="isBigEndian" Type="System.Boolean" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
71357135
</Parameters>
71367136
<Docs>
7137-
<param name="isUnsigned">To be added.</param>
7138-
<param name="isBigEndian">To be added.</param>
7139-
<summary>To be added.</summary>
7140-
<returns>To be added.</returns>
7141-
<remarks>To be added.</remarks>
7137+
<param name="isUnsigned"><see langword="true" /> to use unsigned encoding; otherwise, <see langword="false" />.</param>
7138+
<param name="isBigEndian"><see langword="true" /> to write the bytes in a big-endian byte order; otherwise, <see langword="false" />.</param>
7139+
<summary>Returns the value of this <see cref="T:System.Numerics.BigInteger" /> as a byte array using the fewest number of bytes possible. If the value is zero, returns an array of one byte whose element is 0x00.</summary>
7140+
<returns>The value of the current <see cref="T:System.Numerics.BigInteger" /> object converted to an array of bytes.</returns>
7141+
<remarks>
7142+
<format type="text/markdown">
7143+
<![CDATA[
7144+
7145+
## Remarks
7146+
7147+
The integer value `33022` can be exported in four different arrays:
7148+
7149+
| Properties | Result |
7150+
|--------------------------------------|---------------------------------|
7151+
| `isUnsigned: false, isBigEndian: false` | `new byte[] { 0xFE, 0x80, 0x00 }` |
7152+
| `isUnsigned: false, isBigEndian: true` | `new byte[] { 0x00, 0x80, 0xFE }` |
7153+
| `isUnsigned: true, isBigEndian: false` | `new byte[] { 0xFE, 0x80 } ` |
7154+
| `isUnsigned: true, isBigEndian: true` | `new byte[] { 0x80, 0xFE }` |
7155+
7156+
]]></format>
7157+
</remarks>
7158+
<exception cref="T:System.OverflowException">If <paramref name="isUnsigned" /> is <see langword="true" /> and <see cref="P:System.Numerics.BigInteger.Sign" /> is negative.</exception>
71427159
</Docs>
71437160
</Member>
71447161
<MemberGroup MemberName="ToString">
@@ -7800,13 +7817,14 @@ value Mod 2 = 0
78007817
<Parameter Name="isBigEndian" Type="System.Boolean" Index="3" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
78017818
</Parameters>
78027819
<Docs>
7803-
<param name="destination">To be added.</param>
7804-
<param name="bytesWritten">To be added.</param>
7805-
<param name="isUnsigned">To be added.</param>
7806-
<param name="isBigEndian">To be added.</param>
7807-
<summary>To be added.</summary>
7808-
<returns>To be added.</returns>
7820+
<param name="destination">The destination span to which the resulting bytes should be written.</param>
7821+
<param name="bytesWritten">The number of bytes written to <paramref name="destination" />.</param>
7822+
<param name="isUnsigned"><see langword="true" /> to use unsigned encoding; otherwise, <see langword="false" />.</param>
7823+
<param name="isBigEndian"><see langword="true" /> to write the bytes in a big-endian byte order; otherwise, <see langword="false" />.</param>
7824+
<summary>Copies the value of this <see cref="T:System.Numerics.BigInteger" /> as little-endian twos-complement bytes, using the fewest number of bytes possible. If the value is zero, outputs one byte whose element is 0x00.</summary>
7825+
<returns><see langword="true" /> if the bytes fit in <paramref name="destination" />; <see langword="false" /> if not all bytes could be written due to lack of space.</returns>
78097826
<remarks>To be added.</remarks>
7827+
<exception cref="T:System.OverflowException"><paramref name="isUnsigned" /> is <see langword="true" /> and <see cref="P:System.Numerics.BigInteger.Sign" /> is negative.</exception>
78107828
</Docs>
78117829
</Member>
78127830
<Member MemberName="Zero">
@@ -7856,4 +7874,4 @@ value Mod 2 = 0
78567874
</Docs>
78577875
</Member>
78587876
</Members>
7859-
</Type>
7877+
</Type>

‎xml/System.Reflection/MemberInfoExtensions.xml

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,19 @@
3939
<Parameter Name="member" Type="System.Reflection.MemberInfo" RefType="this" />
4040
</Parameters>
4141
<Docs>
42-
<param name="member">To be added.</param>
43-
<summary>To be added.</summary>
44-
<returns>To be added.</returns>
45-
<remarks>To be added.</remarks>
42+
<param name="member">The member from which to retrieve the token, as reftype.</param>
43+
<summary>Gets a metadata token for the given member, if available.</summary>
44+
<returns>An integer representing the metadata token. The returned token is never nil. If unavailable, an exception is thrown.</returns>
45+
<remarks>
46+
<format type="text/markdown"><![CDATA[
47+
48+
## Remarks
49+
50+
This method throws an exception if a metadata token is not available for the specified member. You can call <xref:System.Reflection.MemberInfoExtensions.HasMetadataToken%2A> to determine whether a metadata token is available before calling this method.
51+
52+
]]></format>
53+
</remarks>
54+
<exception cref="T:System.InvalidOperationException">There is no metadata token available.</exception>
4655
</Docs>
4756
</Member>
4857
<Member MemberName="HasMetadataToken">
@@ -65,11 +74,19 @@
6574
<Parameter Name="member" Type="System.Reflection.MemberInfo" RefType="this" />
6675
</Parameters>
6776
<Docs>
68-
<param name="member">To be added.</param>
69-
<summary>To be added.</summary>
70-
<returns>To be added.</returns>
71-
<remarks>To be added.</remarks>
77+
<param name="member">The member to analyze, as reftype.</param>
78+
<summary>Returns a value that indicates whether a metadata token is available for the specified member.</summary>
79+
<returns><see langword="true" /> if there is a metadata token available for the given member; otherwise, <see langword="false" />.</returns>
80+
<remarks>
81+
<format type="text/markdown"><![CDATA[
82+
83+
## Remarks
84+
85+
<xref:System.Reflection.MemberInfoExtensions.GetMetadataToken%2A> throws an exception if a metadata token is not available for the specified member. So use this method to determine whether a metadata token is available before calling <xref:System.Reflection.MemberInfoExtensions.GetMetadataToken%2A>.
86+
87+
]]></format>
88+
</remarks>
7289
</Docs>
7390
</Member>
7491
</Members>
75-
</Type>
92+
</Type>

‎xml/System.Runtime.CompilerServices/SwitchExpressionException.xml

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,20 @@
1818
</Base>
1919
<Interfaces />
2020
<Docs>
21-
<summary>To be added.</summary>
22-
<remarks>To be added.</remarks>
21+
<summary>Indicates that a switch expression that was non-exhaustive failed to match its input at runtime. The exception optionally contains an object representing the unmatched value.</summary>
22+
<remarks>
23+
<format type="text/markdown"><![CDATA[
24+
25+
## Remarks
26+
27+
A C# example of an expression that would throw this exception:
28+
29+
```csharp
30+
3 switch { 4 => 5 }
31+
```
32+
33+
]]></format>
34+
</remarks>
2335
</Docs>
2436
<Members>
2537
<Member MemberName=".ctor">
@@ -225,4 +237,4 @@
225237
</Docs>
226238
</Member>
227239
</Members>
228-
</Type>
240+
</Type>

‎xml/System.Runtime.InteropServices/SequenceMarshal.xml

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
</Base>
2121
<Interfaces />
2222
<Docs>
23-
<summary>To be added.</summary>
23+
<summary>Provides a collection of methods for interoperating with <see cref="T:System.Buffers.ReadOnlySequence`1" />.</summary>
2424
<remarks>To be added.</remarks>
2525
</Docs>
2626
<Members>
@@ -53,11 +53,11 @@
5353
<Parameter Name="segment" Type="System.ArraySegment&lt;T&gt;" RefType="out" />
5454
</Parameters>
5555
<Docs>
56-
<typeparam name="T">To be added.</typeparam>
57-
<param name="sequence">To be added.</param>
58-
<param name="segment">To be added.</param>
59-
<summary>To be added.</summary>
60-
<returns>To be added.</returns>
56+
<typeparam name="T">The type of the read-only sequence.</typeparam>
57+
<param name="sequence">The read-only sequence from which the array segment will be retrieved.</param>
58+
<param name="segment">The returned array segment.</param>
59+
<summary>Gets an array segment from the underlying read-only sequence.</summary>
60+
<returns><see langword="true" /> if it's possible to retrieve the array segment; otherwise, <see langword="false" /> and a default array segment is returned.</returns>
6161
<remarks>To be added.</remarks>
6262
</Docs>
6363
</Member>
@@ -90,11 +90,11 @@
9090
<Parameter Name="memory" Type="System.ReadOnlyMemory&lt;T&gt;" RefType="out" />
9191
</Parameters>
9292
<Docs>
93-
<typeparam name="T">To be added.</typeparam>
94-
<param name="sequence">To be added.</param>
95-
<param name="memory">To be added.</param>
96-
<summary>To be added.</summary>
97-
<returns>To be added.</returns>
93+
<typeparam name="T">The type of the read-only sequence.</typeparam>
94+
<param name="sequence">The read-only sequence from which the memory will be retrieved.</param>
95+
<param name="memory">The returned read-only memory of type T.</param>
96+
<summary>Attempts to retrieve a read-only memory from the specified read-only sequence.</summary>
97+
<returns><see langword="true" /> if the read-only memory can be retrieved; otherwise, <see langword="false" />.</returns>
9898
<remarks>To be added.</remarks>
9999
</Docs>
100100
</Member>
@@ -130,14 +130,14 @@
130130
<Parameter Name="endIndex" Type="System.Int32" RefType="out" />
131131
</Parameters>
132132
<Docs>
133-
<typeparam name="T">To be added.</typeparam>
134-
<param name="sequence">To be added.</param>
135-
<param name="startSegment">To be added.</param>
136-
<param name="startIndex">To be added.</param>
137-
<param name="endSegment">To be added.</param>
138-
<param name="endIndex">To be added.</param>
139-
<summary>To be added.</summary>
140-
<returns>To be added.</returns>
133+
<typeparam name="T">The type of the read-only sequence.</typeparam>
134+
<param name="sequence">The read-only sequence from which the read-only sequence segment will be retrieved.</param>
135+
<param name="startSegment">The beginning read-only sequence segment.</param>
136+
<param name="startIndex">The initial position.</param>
137+
<param name="endSegment">The ending read-only sequence segment.</param>
138+
<param name="endIndex">The final position.</param>
139+
<summary>Attempts to retrieve a read-only sequence segment from the specified read-only sequence.</summary>
140+
<returns><see langword="true" /> if the read-only sequence segment can be retrieved; otherwise, <see langword="false" />.</returns>
141141
<remarks>To be added.</remarks>
142142
</Docs>
143143
</Member>
@@ -173,13 +173,23 @@
173173
<Parameter Name="value" Type="T" RefType="out" Index="1" FrameworkAlternate="netcore-3.0" />
174174
</Parameters>
175175
<Docs>
176-
<typeparam name="T">To be added.</typeparam>
177-
<param name="reader">To be added.</param>
178-
<param name="value">To be added.</param>
179-
<summary>To be added.</summary>
180-
<returns>To be added.</returns>
181-
<remarks>To be added.</remarks>
176+
<typeparam name="T">The type of the value.</typeparam>
177+
<param name="reader">A reference to the sequence reader.</param>
178+
<param name="value">The returned value if the read was successful. <paramref name="value" /> will be <see langword="default" /> if failed (due to lack of space).</param>
179+
<summary>Attempts to read the specified type out of the buffer. It's dangerous to use this method with arbitrary structs - see remarks for more information.</summary>
180+
<returns><see langword="true" /> if the read attempt was successful, <see langword="false" /> otherwise.</returns>
181+
<remarks>
182+
<format type="text/markdown"><![CDATA[
183+
184+
## Remarks
185+
186+
> [!IMPORTANT]
187+
> The read is a straight copy of bits. If a struct depends on the specific state of its members to behave correctly, this can lead to exceptions.
188+
> If you're reading endian specific integers, use the explicit overloads such as [TryReadLittleEndian(SequenceReader\<Byte>, Int32)](xref:System.Buffers.SequenceReaderExtensions.TryReadLittleEndian%2A).
189+
190+
]]></format>
191+
</remarks>
182192
</Docs>
183193
</Member>
184194
</Members>
185-
</Type>
195+
</Type>

‎xml/System.Threading.Tasks/Parallel.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -949,6 +949,7 @@
949949
-or-
950950

951951
Any methods in the source orderable partitioner return <see langword="null" />.</exception>
952+
<exception cref="T:System.AggregateException">The exception thrown from one of the specified delegates.</exception>
952953
<related type="Article" href="https://docs.microsoft.com/previous-versions/msp-n-p/ff963552(v=pandp.10)">Parallel Loops</related>
953954
</Docs>
954955
</Member>
@@ -2427,4 +2428,4 @@
24272428
</Docs>
24282429
</Member>
24292430
</Members>
2430-
</Type>
2431+
</Type>

‎xml/System.Threading.Tasks/ParallelOptions.xml

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,15 @@
2626
<Interfaces />
2727
<Docs>
2828
<summary>Stores options that configure the operation of methods on the <see cref="T:System.Threading.Tasks.Parallel" /> class.</summary>
29-
<remarks>To be added.</remarks>
29+
<remarks>
30+
<format type="text/markdown"><![CDATA[
31+
32+
## Remarks
33+
34+
By default, methods on the <xref:System.Threading.Tasks.Parallel> class attempt to use all available processors, are non-cancelable, and target the default <xref:System.Threading.Tasks.TaskScheduler> (<xref:System.Threading.Tasks.TaskScheduler.Default?displayProperty=nameWithType>). <xref:System.Threading.Tasks.ParallelOptions> enables overriding these defaults.
35+
36+
]]></format>
37+
</remarks>
3038
<threadsafe>The constructor is thread-safe and may be used by multiple threads concurrently to construct multiple instances. None of the other public members are thread-safe.</threadsafe>
3139
<related type="Article" href="~/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md">Data Parallelism (Task Parallel Library)</related>
3240
</Docs>
@@ -190,4 +198,4 @@
190198
</Docs>
191199
</Member>
192200
</Members>
193-
</Type>
201+
</Type>

0 commit comments

Comments
 (0)