Update Freeze.md

Author: LiangTheDev

specs/Freeze.md

@@ -4,21 +4,24 @@ to access this feature so that invisible WebView can use less resources. We'd ap
 
 
 # Description
-When a WebView in Win32 app becomes invisible, the app calls `TryFreeze` API so that it consumes less memory.
-For an Universal Windows Platform app, the app calls the API in suspended event handler before completing the suspended event.
+You may call the `TryFeezeAsync` API to have the WebView2 consume less memory. This is useful when your Win32 app becomes invisible, or when your Universal Windows Platform app is suspended, during the suspended event handler before completing the suspended event.
 
 # Examples
 ## .Net, WinRT
 ```c#
 async protected void OnSuspending(object sender, SuspendingEventArgs args)
 {
     SuspendingDeferral deferral = args.SuspendingOperation.GetDeferral();
+    // Set webView.Visibility to false first.
+    // WebView2 must be invisible for TryFreezeAsync to succeed.
     webView.Visibility = false;
     await webView.CoreWebView2.TryFreezeAsync();
     deferral.Complete();
 }
 async protected void OnSuspending(object sender, Object args)
 {
+    // Making a WebView2 visible will automatically unfreeze it
+    // But you can also explicitly call Unfreeze without making a WebView2 visible to unfreeze it.
     webView.CoreWebView2.Unfreeze();
     webView.Visibility = true;
 }
@@ -75,18 +78,18 @@ void ViewComponent::Unfreeze()
 ```
 
 # Remarks
-WebView2 controller must be invisible when the API is called. Otherwise, the
+The CoreWebView2Controller must be invisible when the API is called. Otherwise, the
 API fails with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`.   
-Freezing is similar to putting a tab into sleeping in browser. Freezing pauses
+Freezing is similar to putting a tab to sleep in the Edge browser. Freezing pauses
 WebView script timers and animations, minimizes CPU usage for the associated
 browser renderer process and allows the operating system to reuse the memory that was
 used by the renderer process for other processes.   
 See [Sleeping Tabs FAQ](https://techcommunity.microsoft.com/t5/articles/sleeping-tabs-faq/m-p/1705434)
 for conditions that might prevent WebView from being frozen. In those situations,
-TryFreeze operation will fail and the completed handler will be invoked with isSuccessful as false.   
-WebView will be automatically unfrozen when it becomes visible. Therefore, the app normally doesn't have to call Unfreeze.
-The app can call `Unfreeze` and then `TryFreeze` periodically for an invisibile WebView so that the WebView can sync up with
-latest data to show fresh content when it becomes visible.
+The TryFreeze operation will fail and the completed handler will be invoked with isSuccessful as false.   
+The WebView will be automatically unfrozen when it becomes visible. Therefore, the app normally doesn't have to call Unfreeze.
+The app can call `Unfreeze` and then `TryFreeze` periodically for an invisibile WebView so that the invisible WebView can sync up with
+latest data and the page ready to show fresh content when it becomes visible.
 
 # API Notes
 See [API Details](#api-details) section below for API reference.
@@ -97,8 +100,30 @@ See [API Details](#api-details) section below for API reference.
 ```IDL
 interface ICoreWebView2_2 : ICoreWebView2 {
 
+  /// An app may call the `TryFeezeAsync` API to have the WebView2 consume less memory.
+  /// This is useful when a Win32 app becomes invisible, or when a Universal Windows
+  /// Platform app is suspended, during the suspended event handler before completing
+  /// the suspended event.
+  /// The CoreWebView2Controller must be invisible when the API is called. Otherwise, the
+  /// API fails with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`.   
+  /// Freezing is similar to putting a tab to sleep in the Edge browser. Freezing pauses
+  /// WebView script timers and animations, minimizes CPU usage for the associated
+  /// browser renderer process and allows the operating system to reuse the memory that was
+  /// used by the renderer process for other processes.   
+  /// See [Sleeping Tabs FAQ](https://techcommunity.microsoft.com/t5/articles/sleeping-tabs-faq/m-p/1705434)
+  /// for conditions that might prevent WebView from being frozen. In those situations,
+  /// The TryFreeze operation will fail and the completed handler will be invoked with isSuccessful as false.   
+  /// The WebView will be automatically unfrozen when it becomes visible. Therefore, the
+  /// app normally doesn't have to call Unfreeze.
+  /// The app can call `Unfreeze` and then `TryFreeze` periodically for an invisibile WebView so that
+  /// the invisible WebView can sync up with latest data and the page ready to show fresh content
+  /// when it becomes visible.
   HRESULT TryFreeze([in] ICoreWebView2StagingTryFreezeCompletedHandler* handler);
 
+  /// Unfreeze the WebView so that it would resume activities on the web page.
+  /// This API can be called while the WebView2 controller is invisible.
+  /// The app can interact with the WebView immediately after unfreeze.
+  /// WebView will be automatically unfrozen when it becomes visible.
   HRESULT Unfreeze();
 }
 
@@ -117,7 +142,7 @@ namespace Microsoft.Web.WebView2.Core
     public partial class CoreWebView2
     {
         // There are other API in this interface that we are not showing 
-        public Task<int> TryFreezeAsync();
+        public Task<bool> TryFreezeAsync();
         public void Unfreeze();
     }
 }