From cdf93acbb0fa04edc7d1e11a6584fea57094695a Mon Sep 17 00:00:00 2001
From: Steven <stevenwei@microsoft.com>
Date: Mon, 14 Nov 2022 13:06:37 -0800
Subject: [PATCH] addressed comments

---
 specs/LocaleRegion.md | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md
index 34cc37742..1dface8a7 100644
--- a/specs/LocaleRegion.md
+++ b/specs/LocaleRegion.md
@@ -14,9 +14,6 @@ language.
 * The intended value for `LocaleRegion` is in the format of `language[-country]` where `language` is the 
 2-letter code from [ISO 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the 
 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html).
-* By default, the `LocaleRegion` will be set as the value for the Limited option in the browser.
-That means that if the OS region and the display language share the same language code, 
-like 'en-GB' and 'en-US', the value will be set to the OS region.
 
 # Examples
 ```cpp
@@ -51,22 +48,36 @@ public CreateWebView2Controller(IntPtr parentWindow)
 ```cpp
 [uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)]
 interface ICoreWebView2StagingControllerOptions : IUnknown {
-  /// Interface for locale region that is updated through the ControllerOptions
-  /// API.
-  /// The default region for WebView.  It applies to browser UI such as
+  /// The default region for the WebView2.  It applies to JavaScript API
+  /// Intl.DateTimeFormat() which affects string formatting like
   /// in the time/date formats. The intended locale value is in the format of
   /// `language[-country]` where `language` is the 2-letter code from [ISO
   /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the
   /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html).
   ///
+  /// This property will update the environment creation. This is global and immutable, 
+  /// so changes will not be reflected in the existing webviews. They will need to closed
+  /// and reopened in order to see the changes reflected from using the new creation environment.
+  ///
   /// Validation is done on the V8 engine to match on the closest locale
   /// from the passed in locale region value. For example, passing in "en_gb"
   /// will reflect the "en-GB" locale in V8.
   /// If V8 cannot find any matching locale on the input value, it will default
   /// to the display language as the locale.
   ///
-  /// The Windows API `GetLocaleInfoEx` can be used if the LocaleRegion value
-  /// is always set to match the OS region
+  /// The default value for LocaleRegion will be depend on the WebView2 language
+  /// and OS region. If the language portions of the WebView2 language and OS Region
+  /// match, then it will use the OS region. Otherwise, it will use the WebView2
+  /// language.
+  /// | **OS Region** | **WebView2 Language** | **Default WebView2 LocaleRegion** |
+  /// |-----------|-------------------|-------------------------------|
+  /// | en-GB     | en-US             | en-GB                         |
+  /// | es-MX     | en-US             | en-US                         |
+  /// | en-US     | en-GB             | en-US                         |
+  /// The default value can be reset using the empty string.
+  ///
+  /// Use OS specific APIs to determine the OS region to use with this property
+  /// if you want to match the OS. For example:
   ///
   /// ```cpp
   /// int LanguageCodeBufferSize =
@@ -78,15 +89,19 @@ interface ICoreWebView2StagingControllerOptions : IUnknown {
   /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize);
   /// delete[] w_language_code;
   /// return buffer;
-  /// ```
+  /// ``` 
   ///
+  /// ```c#
+  ///   var geographicRegion = new Windows.Globalization.GeographicRegion();
+  ///   var regionCode = geographicRegion.CodeTwoLetter;
+  /// ```
   /// The caller must free the returned string with `CoTaskMemFree`.  See
   /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings).
   /// \snippet AppWindow.cpp RegionLocaleSetting
   // MSOWNERS: stevenwei@microsoft.com
   [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale);
 
-  /// Sets the `Region` property.
+  /// Sets the `LocaleRegion` property.
   // MSOWNERS: stevenwei@microsoft.com
   [propput] HRESULT LocaleRegion([in] LPCWSTR locale);
 }