Skip to content

Commit 8a5dde8

Browse files
carlossanlopcarlossanlop
authored
Automatic port of GC documentation (dotnet#4667)
* Automatic port of GC documentation * Apply suggestions from code review * typo Co-authored-by: carlossanlop <[email protected]>
1 parent 9c002f0 commit 8a5dde8

File tree

4 files changed

+108
-52
lines changed

4 files changed

+108
-52
lines changed

‎xml/System/GC.xml

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -202,12 +202,20 @@
202202
<Parameter Name="pinned" Type="System.Boolean" Index="1" FrameworkAlternate="net-5.0" />
203203
</Parameters>
204204
<Docs>
205-
<typeparam name="T">To be added.</typeparam>
206-
<param name="length">To be added.</param>
207-
<param name="pinned">To be added.</param>
208-
<summary>To be added.</summary>
205+
<typeparam name="T">Specifies the type of the array element.</typeparam>
206+
<param name="length">Specifies the length of the array.</param>
207+
<param name="pinned">Specifies whether the allocated array must be pinned.</param>
208+
<summary>Allocates an array.</summary>
209209
<returns>To be added.</returns>
210-
<remarks>To be added.</remarks>
210+
<remarks>
211+
<format type="text/markdown"><![CDATA[
212+
213+
## Remarks
214+
215+
If pinned is set to `true`, `T` must not be a reference type or a type that contains object references.
216+
217+
]]></format>
218+
</remarks>
211219
</Docs>
212220
</Member>
213221
<Member MemberName="AllocateUninitializedArray&lt;T&gt;">
@@ -238,12 +246,20 @@
238246
<Parameter Name="pinned" Type="System.Boolean" Index="1" FrameworkAlternate="net-5.0" />
239247
</Parameters>
240248
<Docs>
241-
<typeparam name="T">To be added.</typeparam>
242-
<param name="length">To be added.</param>
243-
<param name="pinned">To be added.</param>
244-
<summary>To be added.</summary>
249+
<typeparam name="T">Specifies the type of the array element.</typeparam>
250+
<param name="length">Specifies the length of the array.</param>
251+
<param name="pinned">Specifies whether the allocated array must be pinned.</param>
252+
<summary>Allocates an array while skipping zero-initialization, if possible.</summary>
245253
<returns>To be added.</returns>
246-
<remarks>To be added.</remarks>
254+
<remarks>
255+
<format type="text/markdown"><![CDATA[
256+
257+
## Remarks
258+
259+
If pinned is set to `true`, `T` must not be a reference type or a type that contains object references.
260+
261+
]]></format>
262+
</remarks>
247263
</Docs>
248264
</Member>
249265
<Member MemberName="CancelFullGCNotification">
@@ -911,9 +927,9 @@ This method is most useful in monitoring scenarios for measuring the difference
911927
<Parameter Name="kind" Type="System.GCKind" Index="0" FrameworkAlternate="net-5.0" />
912928
</Parameters>
913929
<Docs>
914-
<param name="kind">To be added.</param>
915-
<summary>To be added.</summary>
916-
<returns>To be added.</returns>
930+
<param name="kind">The kind of collection for which to retrieve memory information.</param>
931+
<summary>Gets garbage collection memory information.</summary>
932+
<returns>An object that contains information about the garbage collector's memory usage.</returns>
917933
<remarks>To be added.</remarks>
918934
</Docs>
919935
</Member>

‎xml/System/GCGenerationInfo.xml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
</Attribute>
2121
</Attributes>
2222
<Docs>
23-
<summary>To be added.</summary>
23+
<summary>Represents the size and the fragmenation of a generation on entry and on exit of the GC reported in <see cref="T:System.GCMemoryInfo" />.</summary>
2424
<remarks>To be added.</remarks>
2525
</Docs>
2626
<Members>
@@ -40,8 +40,8 @@
4040
<ReturnType>System.Int64</ReturnType>
4141
</ReturnValue>
4242
<Docs>
43-
<summary>To be added.</summary>
44-
<value>To be added.</value>
43+
<summary>Gets the fragmentation in bytes on exit from the reported collection.</summary>
44+
<value>A number representing the fragmentation in bytes on exit from the reported collection.</value>
4545
<remarks>To be added.</remarks>
4646
</Docs>
4747
</Member>
@@ -61,8 +61,8 @@
6161
<ReturnType>System.Int64</ReturnType>
6262
</ReturnValue>
6363
<Docs>
64-
<summary>To be added.</summary>
65-
<value>To be added.</value>
64+
<summary>Gets the fragmentation in bytes on entry to the reported collection.</summary>
65+
<value>A number representing the fragmentation in bytes on entry to the reported collection.</value>
6666
<remarks>To be added.</remarks>
6767
</Docs>
6868
</Member>
@@ -82,8 +82,8 @@
8282
<ReturnType>System.Int64</ReturnType>
8383
</ReturnValue>
8484
<Docs>
85-
<summary>To be added.</summary>
86-
<value>To be added.</value>
85+
<summary>Gets the size in bytes on exit from the reported collection.</summary>
86+
<value>A number representing the size in bytes on exit from the reported collection.</value>
8787
<remarks>To be added.</remarks>
8888
</Docs>
8989
</Member>
@@ -103,8 +103,8 @@
103103
<ReturnType>System.Int64</ReturnType>
104104
</ReturnValue>
105105
<Docs>
106-
<summary>To be added.</summary>
107-
<value>To be added.</value>
106+
<summary>Gets the size in bytes on entry to the reported collection.</summary>
107+
<value>A number representing the size in bytes on entry to the reported collection.</value>
108108
<remarks>To be added.</remarks>
109109
</Docs>
110110
</Member>

‎xml/System/GCKind.xml

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,17 @@
1313
<BaseTypeName>System.Enum</BaseTypeName>
1414
</Base>
1515
<Docs>
16-
<summary>To be added.</summary>
17-
<remarks>To be added.</remarks>
16+
<summary>Specifies the kind of a garbage collection.</summary>
17+
<remarks>
18+
<format type="text/markdown"><![CDATA[
19+
20+
## Remarks
21+
22+
A GC can be one of the 3 kinds - ephemeral, full blocking or background.
23+
Their frequencies are very different. Ephemeral GCs happen much more often than the other two kinds. Background GCs usually happen infrequently, and full blocking GCs usually happen very infrequently. In order to sample the very infrequent GCs, collections are separated into kinds so callers can ask for all three kinds while maintaining a reasonable sampling rate, e.g. if you are sampling once every second, without this distinction, you may never observe a background GC. With this distinction, you can always get info of the last GC of the kind you specify.
24+
25+
]]></format>
26+
</remarks>
1827
</Docs>
1928
<Members>
2029
<Member MemberName="Any">
@@ -34,7 +43,8 @@
3443
</ReturnValue>
3544
<MemberValue>0</MemberValue>
3645
<Docs>
37-
<summary>To be added.</summary>
46+
<summary>Any kind of collection.</summary>
47+
<remarks>To be added.</remarks>
3848
</Docs>
3949
</Member>
4050
<Member MemberName="Background">
@@ -54,7 +64,16 @@
5464
</ReturnValue>
5565
<MemberValue>3</MemberValue>
5666
<Docs>
57-
<summary>To be added.</summary>
67+
<summary>A background collection.</summary>
68+
<remarks>
69+
<format type="text/markdown"><![CDATA[
70+
71+
## Remarks
72+
73+
This is always a gen2 collection.
74+
75+
]]></format>
76+
</remarks>
5877
</Docs>
5978
</Member>
6079
<Member MemberName="Ephemeral">
@@ -74,7 +93,8 @@
7493
</ReturnValue>
7594
<MemberValue>1</MemberValue>
7695
<Docs>
77-
<summary>To be added.</summary>
96+
<summary>A gen0 or gen1 collection.</summary>
97+
<remarks>To be added.</remarks>
7898
</Docs>
7999
</Member>
80100
<Member MemberName="FullBlocking">
@@ -94,7 +114,8 @@
94114
</ReturnValue>
95115
<MemberValue>2</MemberValue>
96116
<Docs>
97-
<summary>To be added.</summary>
117+
<summary>A blocking gen2 collection.</summary>
118+
<remarks>To be added.</remarks>
98119
</Docs>
99120
</Member>
100121
</Members>

‎xml/System/GCMemoryInfo.xml

Lines changed: 43 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,16 @@
2323
</Attributes>
2424
<Docs>
2525
<summary>Provides a set of APIs that can be used to retrieve garbage collection information.</summary>
26-
<remarks>To be added.</remarks>
26+
<remarks>
27+
<format type="text/markdown"><![CDATA[
28+
29+
## Remarks
30+
31+
A GC is identified by its Index. which starts from 1 and increases with each GC (see more explanation of it in the Index prooperty).
32+
If you are asking for a GC that does not exist, eg, you called the GC.GetGCMemoryInfo API before a GC happened, or you are asking for a GC of GCKind.FullBlocking and no full blocking GCs have happened, you will get all 0's in the info, including the Index. So you can use Index 0 to detect that no GCs, or no GCs of the kind you specified have happened.
33+
34+
]]></format>
35+
</remarks>
2736
</Docs>
2837
<Members>
2938
<Member MemberName="Compacted">
@@ -42,8 +51,9 @@
4251
<ReturnType>System.Boolean</ReturnType>
4352
</ReturnValue>
4453
<Docs>
45-
<summary>To be added.</summary>
46-
<value>To be added.</value>
54+
<summary>Specifies if this is a compacting GC or not.</summary>
55+
<value>
56+
<see langword="true" /> if this is a compacting GC; <see langword="false" /> otherwise.</value>
4757
<remarks>To be added.</remarks>
4858
</Docs>
4959
</Member>
@@ -63,8 +73,9 @@
6373
<ReturnType>System.Boolean</ReturnType>
6474
</ReturnValue>
6575
<Docs>
66-
<summary>To be added.</summary>
67-
<value>To be added.</value>
76+
<summary>Specifies if this is a concurrent GC (BGC) or not.</summary>
77+
<value>
78+
<see langword="true" /> if this is a concurrent GC (BGC); <see langword="false" /> otherwise.</value>
6879
<remarks>To be added.</remarks>
6980
</Docs>
7081
</Member>
@@ -84,8 +95,8 @@
8495
<ReturnType>System.Int64</ReturnType>
8596
</ReturnValue>
8697
<Docs>
87-
<summary>To be added.</summary>
88-
<value>To be added.</value>
98+
<summary>Gets the number of objects ready for finalization this GC observed.</summary>
99+
<value>A number representing the total objects observed by this GC that are ready for finalization.</value>
89100
<remarks>To be added.</remarks>
90101
</Docs>
91102
</Member>
@@ -146,8 +157,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
146157
<ReturnType>System.Int32</ReturnType>
147158
</ReturnValue>
148159
<Docs>
149-
<summary>To be added.</summary>
150-
<value>To be added.</value>
160+
<summary>Gets the generation this GC collected. Collecting a generation means all its younger generation(s) are also collected.</summary>
161+
<value>A number representing the generation this GC collected.</value>
151162
<remarks>To be added.</remarks>
152163
</Docs>
153164
</Member>
@@ -167,8 +178,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
167178
<ReturnType>System.ReadOnlySpan&lt;System.GCGenerationInfo&gt;</ReturnType>
168179
</ReturnValue>
169180
<Docs>
170-
<summary>To be added.</summary>
171-
<value>To be added.</value>
181+
<summary>Gets the generation information for all generations.</summary>
182+
<value>A read-only span containing the generation information for all generations.</value>
172183
<remarks>To be added.</remarks>
173184
</Docs>
174185
</Member>
@@ -234,8 +245,9 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
234245
<ReturnType>System.Int64</ReturnType>
235246
</ReturnValue>
236247
<Docs>
237-
<summary>To be added.</summary>
238-
<value>To be added.</value>
248+
<summary>The index of this GC. GC indices start with 1 and get increased at the beginning of a GC.
249+
Since the information is updated at the end of a GC, this means you can get the information for a BGC with a smaller index than a foreground GC finished earlier.</summary>
250+
<value>A number representing the index of this GC.</value>
239251
<remarks>To be added.</remarks>
240252
</Docs>
241253
</Member>
@@ -278,8 +290,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
278290
<ReturnType>System.ReadOnlySpan&lt;System.TimeSpan&gt;</ReturnType>
279291
</ReturnValue>
280292
<Docs>
281-
<summary>To be added.</summary>
282-
<value>To be added.</value>
293+
<summary>Gets the pause durations. For blocking GCs there's only 1 pause; for BGC there are 2.</summary>
294+
<value>A timespan representing the pause durations.</value>
283295
<remarks>To be added.</remarks>
284296
</Docs>
285297
</Member>
@@ -299,9 +311,16 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
299311
<ReturnType>System.Double</ReturnType>
300312
</ReturnValue>
301313
<Docs>
302-
<summary>To be added.</summary>
303-
<value>To be added.</value>
304-
<remarks>To be added.</remarks>
314+
<summary>Gets the pause time percentage in the GC so far.</summary>
315+
<value>A number representing the pause time percentage.</value>
316+
<remarks>
317+
<format type="text/markdown"><![CDATA[
318+
## Remarks
319+
320+
If it's 1.2%, this number is 1.2.
321+
322+
]]></format>
323+
</remarks>
305324
</Docs>
306325
</Member>
307326
<Member MemberName="PinnedObjectsCount">
@@ -320,8 +339,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
320339
<ReturnType>System.Int64</ReturnType>
321340
</ReturnValue>
322341
<Docs>
323-
<summary>To be added.</summary>
324-
<value>To be added.</value>
342+
<summary>Gets the number of pinned objects this GC observed.</summary>
343+
<value>A number representing the total pinned objects observed by this GC.</value>
325344
<remarks>To be added.</remarks>
326345
</Docs>
327346
</Member>
@@ -341,8 +360,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but wil
341360
<ReturnType>System.Int64</ReturnType>
342361
</ReturnValue>
343362
<Docs>
344-
<summary>To be added.</summary>
345-
<value>To be added.</value>
363+
<summary>Gets the promoted bytes for this GC.</summary>
364+
<value>A number representing the number of promoted bytes for this GC.</value>
346365
<remarks>To be added.</remarks>
347366
</Docs>
348367
</Member>
@@ -397,8 +416,8 @@ Otherwise, the value of the property is the physical memory on the machine that
397416
<ReturnType>System.Int64</ReturnType>
398417
</ReturnValue>
399418
<Docs>
400-
<summary>To be added.</summary>
401-
<value>To be added.</value>
419+
<summary>Gets the total committed bytes of the managed heap.</summary>
420+
<value>A number representing the total commited bytes of the managed heap.</value>
402421
<remarks>To be added.</remarks>
403422
</Docs>
404423
</Member>

0 commit comments

Comments
 (0)