Resolve comments; Fix typos and grammer errors in doc.

Author: DinahK-2SO

specs/Storage.Pickers/FileOpenPicker.md

@@ -38,18 +38,19 @@ using Microsoft.Windows.Storage.Pickers;
 
 var openPicker = new FileOpenPicker(this.AppWindow.Id)
 {
-    // (Optional) specify the initial location.
-    //     If not specified, default to PickerLocationId.Unspecified.
+    // (Optional) Specify the initial location for the picker. 
+    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
     SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
 
-    // (Optional) specify the text displayed on commit button. 
+    // (Optional) specify the text displayed on the commit button. 
     //     If not specified, the system uses a default label of "Open" (suitably translated).
     CommitButtonText = "Choose selected files",
 
-    // (Optional) specify file extensions filters. If not specified, default to all (*.*)
+    // (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
     FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },
 
-    // (Optional) specify the view mode of the picker dialog. If not specified, default to List.
+    // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
     ViewMode = PickerViewMode.List,
 };
 ```
@@ -62,28 +63,29 @@ using namespace winrt::Microsoft::Windows::Storage::Pickers;
 
 FileOpenPicker openPicker(AppWindow().Id());
 
-// (Optional) specify the initial location.
-//     If not specified, default to PickerLocationId.Unspecified.
+// (Optional) Specify the initial location for the picker. 
+//     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+//     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
 openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
 
-// (Optional) specify the text displayed on commit button. 
+// (Optional) specify the text displayed on the commit button. 
 //     If not specified, the system uses a default label of "Open" (suitably translated).
 openPicker.CommitButtonText(L"Choose selected files");
 
-// (Optional) specify file extensions filters. If not specified, default to all (*.*)
+// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
 openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });
 
-// (Optional) specify the view mode of the picker dialog. If not specified, default to List.
-picker.ViewMode(PickerViewMode::List);
+// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
+openPicker.ViewMode(PickerViewMode::List);
 ```
 
 ## FileOpenPicker.PickSingleFileAsync
 
-Displays a UI element that allows user to choose and open one file.
+Displays a UI element that allows the user to choose and open one file.
 
-Returns a light weight object that has the path of the picked file.
+Returns a lightweight object that has the path of the picked file.
 
-Return null if the file dialog was cancelled or closed without selection.
+Returns `null` if the file dialog was cancelled or closed without a selection.
 
 ### Examples
 
@@ -128,11 +130,11 @@ else
 
 ## FileOpenPicker.PickMultipleFilesAsync
 
-Displays a UI element that allows user to choose and open multiple files.
+Displays a UI element that allows the user to choose and open multiple files.
 
-Returns a collection of light weight objects that has the path of picked files.
+Returns a collection of lightweight objects that have the path of the picked files.
 
-Return an empty list (Count = 0) if the file dialog's cancelled or closed without selection.
+Returns an empty list (`Count` = 0) if the file dialog was cancelled or closed without a selection.
 
 ### Examples
 

specs/Storage.Pickers/FileSavePicker.md

@@ -39,25 +39,26 @@ using Microsoft.Windows.Storage.Pickers;
 
 var savePicker = new FileSavePicker(this.AppWindow.Id)
 {
-    // (Optional) specify the initial location.
-    //     If not specified, default to PickerLocationId.Unspecified.
+    // (Optional) Specify the initial location for the picker. 
+    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
     SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
 
     // (Optional) specify the default file name. If not specified, use system default.
     SuggestedFileName = "My Document",
 
-    // (Optional) specify the text displayed on commit button. 
-    //     If not specified, the system uses a default label of "Open" (suitably translated).
+    // (Optional) specify the text displayed on the commit button. 
+    //     If not specified, the system uses a default label of "Save" (suitably translated).
     CommitButtonText = "Save Document",
 
-    // (Optional) categorized extensions types. If not specified, allow All Files (*.*)
-    //     Note that when allow All Files (*.*), end users can save a file without extension.
+    // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
+    //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
     FileTypeChoices = {
         { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
     },
 
-    // (Optional) specify the default file extension (will be appended after the default file name).
-    //      If not specified, will not appended after the default extension.
+    // (Optional) specify the default file extension (will be appended to SuggestedFileName).
+    //      If not specified, no extension will be appended.
     DefaultFileExtension = ".txt",
 };
 ```
@@ -70,37 +71,38 @@ using namespace winrt::Microsoft::Windows::Storage::Pickers;
 
 FileSavePicker savePicker(AppWindow().Id());
 
-// (Optional) specify the initial location.
-//     If not specified, default to PickerLocationId.Unspecified.
+// (Optional) Specify the initial location for the picker. 
+//     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+//     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
 savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
 
 // (Optional) specify the default file name. If not specified, use system default.
 savePicker.SuggestedFileName(L"NewDocument");
 
-// (Optional) specify the text displayed on commit button. 
-//     If not specified, the system uses a default label of "Open" (suitably translated).
+// (Optional) specify the text displayed on the commit button. 
+//     If not specified, the system uses a default label of "Save" (suitably translated).
 savePicker.CommitButtonText(L"Save Document");
 
-// (Optional) categorized extensions types. If not specified, allow All Files (*.*)
-//     Note that when allow All Files (*.*), end users can save a file without extension.
+// (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
+//     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
 savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
 
-// (Optional) specify the default file extension (will be appended after the default file name).
-//      If not specified, will not appended after the default extension.
+// (Optional) specify the default file extension (will be appended to SuggestedFileName).
+//      If not specified, no extension will be appended.
 savePicker.DefaultFileExtension(L".txt");
 ```
 
 ## Setting the FileSavePicker.SuggestedSaveFilePath Property
 
-The `SuggestedSaveFilePath` property of `FileSavePicker` dictates 2 key aspects of the save file 
+The `SuggestedSaveFilePath` property of `FileSavePicker` dictates two key aspects of the save file 
 dialog's initial state:
 
 *   **Initial Directory:** The dialog defaults to the directory of the `SuggestedSaveFilePath`. 
 
     This behavior overrides any picker-specific remembered folder settings and ensures the dialog 
     opens in the suggested file's parent folder.
 
-*   **Pre-filled File Name:** The file name field in the dialog is pre-populated with the name of 
+*   **Pre-filled File Name:** The file name field in the dialog is pre-populated with the name from 
 the `SuggestedSaveFilePath`. 
 
     This file name overrides the `FileSavePicker.SuggestedFileName` property if both are set.
@@ -111,7 +113,7 @@ C#
 using Microsoft.Windows.Storage.Pickers;
 
 var savePicker = new FileSavePicker(this.AppWindow.Id);
-savePicker.SuggestedSaveFilePath(@"C:\temp\MyProject\MyFile.txt");
+savePicker.SuggestedSaveFilePath = @"C:\temp\MyProject\MyFile.txt";
 ```
 
 C++
@@ -120,34 +122,42 @@ C++
 using namespace winrt::Microsoft::Windows::Storage::Pickers;
 
 FileSavePicker savePicker(AppWindow().Id());
-bool isSuccess = savePicker.SuggestedSaveFilePath(L"C:\\temp\\MyProject\\MyFile.txt");
+savePicker.SuggestedSaveFilePath(L"C:\\temp\\MyProject\\MyFile.txt");
 ```
 
-### The Parsing Logic of Setting SuggestedSaveFilePath
+### The Parsing Logic
 
-`SuggestedSaveFilePath` takes whatever after **the last slash** to fill in the file name box, 
-as long as the part before the last slash is a valid and existing folder. 
+The `SuggestedSaveFilePath` property is parsed to set the directory and file name in the 
+save dialog.
 
-It allows the value to be set to an empty string. However, it raises invalid argument exception 
-if the non-empty input doesn't contain have a folder path.
+- The substring before the final path separator (`\`) is used as the initial directory. 
+This part must be written in the format of a folder path.
+- The substring after the final path separator is used as the suggested file name.
+- If `SuggestedSaveFilePath` is set to an empty string, the property is cleared and will not take 
+effect when launching the save dialog.
+- If the provided path is a non-empty string but it does not have a folder path 
+(e.g., `"MyFile.txt"`), an `InvalidArgumentException` will be thrown.
 
-Here're some examples about the parsing logic:
+The following table illustrates the parsing behavior:
+
+| `SuggestedSaveFilePath` Input | Resulting Initial Directory | Resulting File Name |
+|-------------------------------|-----------------------------|---------------------|
+| `'C:\temp\MyProject\MyFile.txt'` | `'C:\temp\MyProject'` | `'MyFile.txt'` |
+| `'C:\temp\MyProject\.git\'` | `'C:\temp\MyProject\.git'` | `''` (empty) |
+| `'C:\temp\MyProject\.git'` | `'C:\temp\MyProject'` | `'.git'` |
+| `'C:\servers\www.bing.com\'` | `'C:\servers\www.bing.com'` | `''` (empty) |
+| `'C:\servers\www.bing.com'` | `'C:\servers'` | `'www.bing.com'` |
+| `''` (empty string) | null |
+| `'MyFile.txt'` | Throws `InvalidArgumentException` | Throws `InvalidArgumentException` |
 
-|Input path string | Set folder | Set file name |
-|------------------|------------|---------------|
-|`'C:\temp\MyProject\MyFile.txt'`|`'C:\temp\MyProject'`| `'MyFile.txt'`|
-|`'C:\temp\MyProject\.git\'`|`'C:\temp\MyProject\.git'`| `''`|
-|`'C:\temp\MyProject\.git'`|`'C:\temp\MyProject'`| `'.git'`|
-|`'C:\servers\www.bing.com\'`|`'C:\servers\www.bing.com'`| `''`|
-|`'C:\servers\www.bing.com'`|`'C:\servers`| `'www.bing.com'`|
 
 ## FileSavePicker.PickSaveFileAsync
 
 Displays a UI element that allows the user to configure the file path to save.
 
-Returns a light weight object that has the path of the saved file.
+Returns a lightweight object that has the path of the saved file.
 
-Returns null if the file dialog was cancelled or closed without saved file.
+Returns `null` if the file dialog was cancelled or closed without saving a file.
 
 ### Examples
 

specs/Storage.Pickers/FolderPicker.md

@@ -42,11 +42,12 @@ using Microsoft.Windows.Storage.Pickers;
 
 var folderPicker = new FolderPicker(this.AppWindow.Id)
 {
-    // (Optional) specify the initial location.
-    //     If not specified, default to PickerLocationId.Unspecified.
+    // (Optional) Specify the initial location for the picker. 
+    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
     SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
 
-    // (Optional) specify the text displayed on commit button. 
+    // (Optional) specify the text displayed on the commit button. 
     //     If not specified, the system uses a default label of "Open" (suitably translated).
     CommitButtonText = "Select Folder",
 
@@ -63,11 +64,12 @@ using namespace winrt::Microsoft::Windows::Storage::Pickers;
 
 FolderPicker folderPicker(AppWindow().Id());
 
-// (Optional) specify the initial location.
-//     If not specified, default to PickerLocationId.Unspecified.
+// (Optional) Specify the initial location for the picker. 
+//     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
+//     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
 folderPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
 
-// (Optional) specify the text displayed on commit button. 
+// (Optional) specify the text displayed on the commit button. 
 //     If not specified, the system uses a default label of "Open" (suitably translated).
 folderPicker.CommitButtonText(L"Select Folder");
 
@@ -79,9 +81,9 @@ folderPicker.ViewMode(PickerViewMode::List);
 
 Displays a UI element that allows the user to choose a folder.
 
-Returns a light weight object that has the path of the picked folder.
+Returns a lightweight object that has the path of the picked folder.
 
-Returns null if the file dialog was cancelled or closed without selection.
+Returns `null` if the file dialog was cancelled or closed without a selection.
 
 ### Examples
 

specs/Storage.Pickers/Microsoft.Windows.Storage.Pickers.md

@@ -8,42 +8,42 @@ design, but with key improvements for desktop scenarios.
 
 # Background
 
-The new `Microsoft.Windows.Storage.Pickers` API addresses three critical limitations of the UWP file 
+The new `Microsoft.Windows.Storage.Pickers` API addresses two critical limitations of the UWP file 
 and folder pickers on Apps developed with WinAppSDK/WinUI 3:
 
 1. **Elevated Process Support**: The existing [Windows.Storage.Pickers](https://learn.microsoft.com/en-us/uwp/api/windows.storage.pickers) 
-APIs do not work when running as an administrator. The new API enables file and folder selection in 
-elevated mode.
+APIs do not work when the application is running as an administrator. The new API enables file and 
+folder selection in elevated mode.
 
 2. **Simplified Usage in WinUI 3**: Using the existing UWP pickers in WinUI 3 requires initializing 
-window handle for window association. The new pickers eliminate this requirement by accepting a 
+a window handle for window association. The new pickers eliminate this requirement by accepting a 
 `WindowId` directly in the constructor, making them easier to use.
 
 # Key Differences
-*Spec Note: Here are some key differences from the UWP Windows.Storage.Pickers:*
-1. *Unlike the existing `Windows.Storage.Pickers` API which returns `StorageFile/StorageFolder` 
+*Spec Note: Here are some key differences from the UWP `Windows.Storage.Pickers`:*
+1. *Unlike the existing `Windows.Storage.Pickers` API which returns `StorageFile`/`StorageFolder` 
 objects, this new API returns string-based paths through `PickFileResult` and `PickFolderResult` 
 classes. This design choice simplifies the API and avoids complications with storage capabilities 
 in elevated scenarios.*
-1. *Similarly, the `StorageFile` type property `FileSavePicker.SuggestedSaveFile` is also replaced
-by a string type `FileSavePicker.SuggestedSaveFilePath`.*
-1. *All new pickers are designed specifically for desktop apps and uses a `WindowId` property to 
+1. *Similarly, the `StorageFile` type property `FileSavePicker.SuggestedSaveFile` is replaced
+by a string type property `FileSavePicker.SuggestedSaveFilePath`.*
+1. *All new pickers are designed specifically for desktop apps and use a `WindowId` property to 
 link the picker to its host window, replacing the `WinRT.Interop.InitializeWithWindow.Initialize` 
 pattern.*
-1. The new pickers allow developers to use pickers without requiring `FileTypeFilter` or 
+1. The new pickers allow developers to use them without requiring `FileTypeFilter` or 
 `FileTypeChoices` to be specified. While UWP pickers throw exceptions when these properties are not 
-set, the new pickers default to show all file when developers don't explicitly configure these 
+set, the new pickers default to showing all files when developers do not explicitly configure these 
 properties.
-1. *HomeGroup location has been excluded from the new `PickerLocationId` enum as it's no longer 
-supported in Windows 10 and later*
-1. *FolderPicker.FileTypeFilter has been exluded as it was not functionally appropriate for folder 
-selection*
-1. *Excluding methods and properties that are already marked as deprecated, or "Do not use". 
-e.g. `PickSingleFileAndContinue`, `ContinuationData`, `ResumePickSingleFileAsync`, etc*
+1. *The `HomeGroup` location has been excluded from the new `PickerLocationId` enum as it is 
+no longer supported in Windows 10 and later.*
+1. *`FolderPicker.FileTypeFilter` has been excluded as it was not functionally appropriate for folder 
+selection.*
+1. *Excluding methods and properties that are already marked as deprecated or "Do not use". 
+e.g., `PickSingleFileAndContinue`, `ContinuationData`, `ResumePickSingleFileAsync`, etc.*
 1. *Excluding methods and properties for [multi-user-mode](https://learn.microsoft.com/en-us/previous-versions/windows/uwp/xbox-apps/multi-user-applications), 
-as the new APIs are currently designed for desktop scenarios where each user has their own 
-interactive session and each session is completely independent of the other sessions on the device, 
-instead of Xbox One or other multi-user devices.*
+because the new APIs are currently designed for desktop scenarios where each user has their own 
+interactive session, and each session is completely independent of the other sessions on the device.
+This is in contrast to Xbox One or other multi-user devices.*
 
 # Conceptual pages
 
@@ -52,7 +52,7 @@ instead of Xbox One or other multi-user devices.*
 ## Classes
 
 Note: Developers should specify a window id to associate the picker with an owner window before 
-showing UI.
+showing the UI.
 
 | **Class**        | **Description** |
 |------------------|-----------------|
@@ -67,7 +67,7 @@ showing UI.
 | **Enum** | **Description** |
 |----------|-----------------|
 |[PickerLocationId](PickerLocationId.md)| Identifies the storage location that the file picker presents to the user. |
-|[PickerViewMode](PickerViewMode.md)    | Indicates the view mode that the file picker is using to present items.    |
+|[PickerViewMode](PickerViewMode.md)    | Indicates the view mode that the file picker uses to present items.    |
 
 ## Definition