Update docs about refreshable Process properties (dotnet#5174)

* Apply code review suggestion

Co-authored-by: Petr Onderka <[email protected]>

* make sure all refreshable properties are  documented

* Apply code review suggestion: current -> most up to date

* address code review feedback: add remarks to other refreshable properties

Co-authored-by: Petr Onderka <[email protected]>

Author: adamsitnik

xml/System.Diagnostics/Process.xml

@@ -256,6 +256,8 @@
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed base priority of the process. To get the most up to date base priority, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+
  The <xref:System.Diagnostics.Process.BasePriority%2A> of the process is the starting priority for threads created within the associated process. You can view information about the base priority through the System Monitor's Priority Base counter.  
 
  Based on the time elapsed or other boosts, the operating system can change the base priority when a process should be placed ahead of others.  
@@ -1982,6 +1984,8 @@ There are problems accessing the performance counter APIs used to get process in
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed handle count. To get the most up to date handle count, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+
  Handles provide a way for a process to refer to objects. A process can obtain handles to files, resources, message queues, and many other operating system objects. The operating system reclaims the memory associated with the process only when the handle count is zero.  
 
  ]]></format>
@@ -2536,7 +2540,7 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The main window is the window opened by the process that currently has the focus (the <xref:System.Windows.Forms.Form.TopLevel%2A> form). You must use the <xref:System.Diagnostics.Process.Refresh%2A> method to refresh the <xref:System.Diagnostics.Process> object to get the current main window handle if it has changed. In general, because the window handle is cached, use <xref:System.Diagnostics.Process.Refresh%2A> beforehand to guarantee that you'll retrieve the current handle.  
+ The main window is the window opened by the process that currently has the focus (the <xref:System.Windows.Forms.Form.TopLevel%2A> form). You must use the <xref:System.Diagnostics.Process.Refresh%2A> method to refresh the <xref:System.Diagnostics.Process> object to get the most up to date main window handle if it has changed. In general, because the window handle is cached, use <xref:System.Diagnostics.Process.Refresh%2A> beforehand to guarantee that you'll retrieve the current handle.  
 
  You can get the <xref:System.Diagnostics.Process.MainWindowHandle%2A> property only for processes that are running on the local computer. The <xref:System.Diagnostics.Process.MainWindowHandle%2A> property is a value that uniquely identifies the window that is associated with the process.  
 
@@ -2612,7 +2616,7 @@ The calling process is a member of the associated process' descendant tree.</exc
  If you have just started a process and want to use its main window title, consider using the <xref:System.Diagnostics.Process.WaitForInputIdle%2A> method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, the system throws an exception.  
 
 > [!NOTE]
->  The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the <xref:System.Diagnostics.Process.Refresh%2A> method to refresh the <xref:System.Diagnostics.Process> object to get the current main window handle if it has changed.  
+>  The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the <xref:System.Diagnostics.Process.Refresh%2A> method to refresh the <xref:System.Diagnostics.Process> object to get the most up to date main window handle if it has changed.  
 
 
 
@@ -2849,6 +2853,8 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed modules. To get the most up to date information, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
  A process module represents a.dll or .exe file that is loaded into a particular process. A <xref:System.Diagnostics.ProcessModule> instance lets you view information about a module, including the module name, file name, and module memory details.  
 
  A process can load multiple modules into memory. For example,.exe files that load additional .dll files have multiple modules.  
@@ -2989,7 +2995,9 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of nonpaged system memory used by the process, in bytes. System memory is the physical memory used by the operating system, and is divided into paged and nonpaged pools. Nonpaged memory allocations remain in system memory and are not paged out to the virtual memory paging file.  
+ The value returned by this property represents the most recently refreshed size of nonpaged system memory used by the process, in bytes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
+ System memory is the physical memory used by the operating system, and is divided into paged and nonpaged pools. Nonpaged memory allocations remain in system memory and are not paged out to the virtual memory paging file.  
 
  This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Pool Nonpaged Bytes** performance counter for the process.  
 
@@ -3263,7 +3271,9 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of memory in the virtual memory paging file used by the process, in bytes. The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of memory used by the operating system for the process, use the <xref:System.Diagnostics.Process.PagedSystemMemorySize64%2A> property.  
+ The value returned by this property represents the most recently refreshed size of memory in the virtual memory paging file used by the process, in bytes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
+ The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of memory used by the operating system for the process, use the <xref:System.Diagnostics.Process.PagedSystemMemorySize64%2A> property.  
 
  This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Page File Bytes** performance counter for the process.  
 
@@ -3908,6 +3918,8 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed temporary priority boost. To get the most up to date value, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
  When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (<xref:System.Diagnostics.ProcessPriorityClass.Normal>, <xref:System.Diagnostics.ProcessPriorityClass.High>, or <xref:System.Diagnostics.ProcessPriorityClass.RealTime>), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The <xref:System.Diagnostics.Process.PriorityBoostEnabled%2A> setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the <xref:System.Diagnostics.Process.PriorityBoostEnabled%2A> property to `false`.  
 
 > [!NOTE]
@@ -3974,7 +3986,9 @@ The calling process is a member of the associated process' descendant tree.</exc
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
-## Remarks  
+## Remarks
+ The value returned by this property represents the most recently refreshed priority of the process. To get the most up to date priority, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+
  A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the <xref:System.Diagnostics.ProcessPriorityClass> enumeration, which lets you set the process priority to <xref:System.Diagnostics.ProcessPriorityClass.Idle>, <xref:System.Diagnostics.ProcessPriorityClass.Normal>, <xref:System.Diagnostics.ProcessPriorityClass.High>, <xref:System.Diagnostics.ProcessPriorityClass.AboveNormal>, <xref:System.Diagnostics.ProcessPriorityClass.BelowNormal>, or <xref:System.Diagnostics.ProcessPriorityClass.RealTime>. Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the <xref:System.Diagnostics.Process.PriorityBoostEnabled%2A> to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state.  
 
  The <xref:System.Diagnostics.Process.BasePriority%2A> property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the <xref:System.Diagnostics.Process.BasePriority%2A> property to set the priority of a process. To change the priority, use the <xref:System.Diagnostics.Process.PriorityClass%2A> property, which gets or sets the overall priority category for the process.  
@@ -4129,7 +4143,7 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of memory used by the process, in bytes, that cannot be shared with other processes.  
+ The value returned by this property represents the most recently refreshed size of memory used by the process, in bytes, that cannot be shared with other processes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
 
  This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Private Bytes** performance counter for the process.  
 
@@ -4337,6 +4351,8 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed affinity of the process. To get the most up to date affinity, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
  In Windows 2000 and later, a thread in a process can migrate from processor to processor, with each migration reloading the processor cache. Under heavy system loads, specifying which processor should run a specific thread can improve performance by reducing the number of times the processor cache is reloaded. The association between a processor and a thread is called the processor affinity.  
 
  Each processor is represented as a bit. Bit 0 is processor one, bit 1 is processor two, and so forth. If you set a bit to the value 1, the corresponding processor is selected for thread assignment. When you set the <xref:System.Diagnostics.Process.ProcessorAffinity%2A> value to zero, the operating system's scheduling algorithms set the thread's affinity. When the <xref:System.Diagnostics.Process.ProcessorAffinity%2A> value is set to any nonzero value, the value is interpreted as a bitmask that specifies those processors eligible for selection.  
@@ -4478,6 +4494,8 @@ The calling process is a member of the associated process' descendant tree.</exc
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed status. To get the most up to date status, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+
  If a process has a user interface, the <xref:System.Diagnostics.Process.Responding%2A> property contacts the user interface to determine whether the process is responding to user input. If the interface does not respond immediately, the <xref:System.Diagnostics.Process.Responding%2A> property returns `false`. Use this property to determine whether the interface of the associated process has stopped responding.  
 
  If the process does not have a <xref:System.Diagnostics.Process.MainWindowHandle%2A>, this property returns `true`.  
@@ -5794,6 +5812,8 @@ The file specified in the <paramref name="fileName" /> could not be found.
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ The value returned by this property represents the most recently refreshed threads. To get the most up to date information, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+
  A thread executes code in a process. Each process is started with a single thread, its primary thread. Any thread can create additional threads. Threads within a process share the address space of the process.  
 
  Use <xref:System.Diagnostics.ProcessThread> to get all the threads associated with the current process. The primary thread is not necessarily at index zero in the array.  
@@ -6106,7 +6126,9 @@ The file specified in the <paramref name="fileName" /> could not be found.
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of virtual memory used by the process, in bytes. The operating system maps the virtual address space for each process either to pages loaded in physical memory, or to pages stored in the virtual memory paging file on disk.  
+ The value returned by this property represents the most recently refreshed size of virtual memory used by the process, in bytes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
+ The operating system maps the virtual address space for each process either to pages loaded in physical memory, or to pages stored in the virtual memory paging file on disk.  
 
  This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Virtual Bytes** performance counter for the process.  
 
@@ -6545,7 +6567,9 @@ Calling this method will set <xref:System.Diagnostics.Process.EnableRaisingEvent
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of working set memory used by the process, in bytes. The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault.  
+ The value returned by this property represents the most recently refreshed size of working set memory used by the process, in bytes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
+ The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault.  
 
  The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including the process modules and the system libraries.  
 
@@ -6622,7 +6646,9 @@ Calling this method will set <xref:System.Diagnostics.Process.EnableRaisingEvent
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The value returned by this property represents the current size of working set memory used by the process, in bytes. The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault.  
+ The value returned by this property represents the most recently refreshed size of working set memory used by the process, in bytes. To get the most up to date size, you need to call <xref:System.Diagnostics.Process.Refresh> method first.
+ 
+ The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault.  
 
  The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including instructions in the process modules and the system libraries.