Add remarks about GC memory info (dotnet#8445)

Author: gewarren

xml/System/GCMemoryInfo.xml

@@ -30,7 +30,7 @@
 
 ## Remarks
 
-A garbage collection (GC) is identified by its <xref:System.GCMemoryInfo.Index>, which starts from 1 and increases with each GC. If you are asking for a GC that doesn't exist, for example, you called the <xref:System.GC.GetGCMemoryInfo%2A> method before a GC happened, or you're asking for a GC of <xref:System.GCKind.FullBlocking?displayProperty=nameWithType> and no full blocking GCs have happened, you will get all 0's in the info, including the <xref:System.GCMemoryInfo.Index>. You can use index 0 to detect that no GCs, or no GCs of the kind you specified, have occurred.
+A garbage collection (GC) is identified by its <xref:System.GCMemoryInfo.Index>, which starts from 1 and increases with each GC. If you ask for a GC that doesn't exist, you'll get all 0's in the info, including the <xref:System.GCMemoryInfo.Index>. For example, you'll get 0's if you call the <xref:System.GC.GetGCMemoryInfo%2A> method before a GC has happened, or you ask for a GC of <xref:System.GCKind.FullBlocking?displayProperty=nameWithType> and no full blocking GCs have happened. You can use index 0 to detect that no GCs, or no GCs of the kind you specified, have occurred.
 
           ]]></format>
     </remarks>
@@ -57,7 +57,7 @@ A garbage collection (GC) is identified by its <xref:System.GCMemoryInfo.Index>,
         <summary>Gets a value that indicates if this is a compacting GC or not.</summary>
         <value>
           <see langword="true" /> if this is a compacting GC; <see langword="false" /> otherwise.</value>
-        <remarks>To be added.</remarks>
+        <remarks>A compacting GC is when space occupied by dead objects is reclaimed and surviving objects are compacted.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Concurrent">
@@ -82,6 +82,7 @@ A garbage collection (GC) is identified by its <xref:System.GCMemoryInfo.Index>,
         <value>
           <see langword="true" /> if this is a concurrent GC (background GC); <see langword="false" /> otherwise.</value>
         <remarks>To be added.</remarks>
+        <related type="Article" href="/dotnet/standard/garbage-collection/background-gc">Background garbage collection</related>
       </Docs>
     </Member>
     <Member MemberName="FinalizationPendingCount">
@@ -243,7 +244,7 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but is
       <Docs>
         <summary>Gets the high memory load threshold when the last garbage collection occurred.</summary>
         <value>The high memory load threshold, in bytes, when the last garbage collection occurred.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Most of the GC performance heuristics are based on per-process measurements. However, to avoid paging, GC is aware of the global physical memory load on the machine or VM or in the container. GC recognizes a certain memory load percentage as a "high memory load situation". When the memory load percentage is over that threshold, GC becomes more aggressive and will do more full blocking GCs if necessary to reduce the heap size.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Index">
@@ -264,10 +265,10 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but is
         <ReturnType>System.Int64</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the index of this GC. GC indices start with 1 and are increased at the beginning of a GC.
-            Since the information is updated at the end of a GC, this means you can get the information for a background GC with a smaller index than a foreground GC that finished earlier.</summary>
+        <summary>Gets the index of this GC.</summary>
         <value>The index of this GC.</value>
-        <remarks>To be added.</remarks>
+        <remarks>GC indices start with 1 and are increased at the beginning of a GC.
+            Since the information is updated at the end of a GC, this means you can get the information for a background GC with a smaller index than a foreground GC that finished earlier.</remarks>
       </Docs>
     </Member>
     <Member MemberName="MemoryLoadBytes">
@@ -292,7 +293,8 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but is
       <Docs>
         <summary>Gets the physical memory load when the last garbage collection occurred.</summary>
         <value>The physical memory load, in bytes, when the last garbage collection occurred.</value>
-        <remarks>Data is only brought into physical memory on first touch. If you allocated a big object but haven't actually used it, most of its memory isn't in physical memory. In this case, the allocation won't affect the memory load significantly.</remarks>
+        <remarks><para>On Windows, memory load is a field in the [MEMORYSTATUS structure](/windows/win32/api/winbase/ns-winbase-memorystatus). It's a number between 0 and 100 that specifies the approximate percentage of physical memory that's in use (0 indicates no memory use and 100 indicates full memory use). Corresponding information is given on other operating systems.</para>
+        <para>Data is only brought into physical memory on first touch. If you allocated a big object but haven't actually used it, most of its memory isn't in physical memory. In this case, the allocation won't affect the memory load significantly.</para></remarks>
       </Docs>
     </Member>
     <Member MemberName="PauseDurations">
@@ -313,9 +315,9 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but is
         <ReturnType>System.ReadOnlySpan&lt;System.TimeSpan&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the pause durations. For blocking GCs, there is one pause; for background GC, there are two.</summary>
+        <summary>Gets the durations of the pauses when all managed threads are suspended.</summary>
         <value>A timespan representing the pause durations.</value>
-        <remarks>To be added.</remarks>
+        <remarks> For blocking GCs, there is one pause. Pauses for background GC are illustrated at [Background workstation vs. server GC](/dotnet/standard/garbage-collection/background-gc#background-workstation-vs-server-gc).</remarks>
       </Docs>
     </Member>
     <Member MemberName="PauseTimePercentage">
@@ -384,7 +386,7 @@ The memory after `OBJ_D` is not considered part of the `FragmentedBytes` but is
       <Docs>
         <summary>Gets the promoted bytes for this GC.</summary>
         <value>The number of promoted bytes for this GC.</value>
-        <remarks>To be added.</remarks>
+        <remarks>The promoted bytes represent the objects from the generations that the garbage collection is collecting that survived.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TotalAvailableMemoryBytes">
@@ -444,7 +446,7 @@ Otherwise, the value of the property is the physical memory on the machine that
       <Docs>
         <summary>Gets the total committed bytes of the managed heap.</summary>
         <value>The total committed bytes of the managed heap.</value>
-        <remarks>To be added.</remarks>
+        <remarks>The total committed bytes is the amount of backing store for the memory. On Windows, bytes are committed when `VirtualAlloc` is called with `MEM_COMMIT`. On Linux, bytes are committed when the page mapping is changed to <code>PROT_WRITE | PROT_READ</code>.</remarks>
       </Docs>
     </Member>
   </Members>