Improve parameter descriptions and examples (#11381)

* Improve parameter descriptions and examples

* fix code fence

reference/5.1/Microsoft.PowerShell.Management/Split-Path.md

@@ -79,42 +79,61 @@ HKCU:
 
 This command returns only the qualifier of the path. The qualifier is the drive.
 
-### Example 2: Display filenames
+### Example 2: Display filename portion of the path
+
+When using the **Leaf** parameter, `Split-Path` returns only the last item in the path string
+supplied, regardless whether that item is a file or a directory.
 
 ```powershell
-Split-Path -Path "C:\Test\Logs\*.log" -Leaf -Resolve
+Split-Path -Path .\folder1\*.txt -Leaf
 ```
 
 ```Output
-Pass1.log
-Pass2.log
-...
+*.txt
 ```
 
-This command displays the files that are referenced by the split path. Because this path is split to
-the last item, also known as the leaf, the command displays only the filenames.
+```powershell
+Split-Path -Path .\folder1\*.txt -Leaf -Resolve
+```
 
-The **Resolve** parameter tells `Split-Path` to display the items that the split path references,
-instead of displaying the split path.
+```Output
+file1.txt
+file2.txt
+```
 
-Like all `Split-Path` commands, this command returns strings. It doesn't return **FileInfo** objects
-that represent the files.
+When you use the **Resolve** parameter, `Split-Path` resolves the path string provided and returns
+the items referenced by the path.
 
 ### Example 3: Get the parent container
 
+When using the **Parent** parameter, `Split-Path` returns only the parent container portion of the
+path string supplied. If the **Path** string doesn't contain a parent container, `Split-Path`
+returns an empty string.
+
+```powershell
+Split-Path -Path .\folder1\file1.txt -Parent
+```
+
+```Output
+.\folder1
+```
+
 ```powershell
-Split-Path -Parent "C:\WINDOWS\system32\WindowsPowerShell\V1.0\about_*.txt"
+Split-Path -Path .\folder1\file1.txt -Parent -Resolve
 ```
 
 ```Output
-C:\WINDOWS\system32\WindowsPowerShell\V1.0
+D:\temp\test\folder1
 ```
 
-This command returns only the parent containers of the path. Because it doesn't include any
-parameters to specify the split, `Split-Path` uses the split location default, which is **Parent**.
+When you use the **Resolve** parameter, `Split-Path` resolves the path string provided and returns
+the full path of the parent container.
 
 ### Example 4: Determines whether a path is absolute
 
+This command determines whether the path is relative or absolute. In this case, because the path is
+relative to the current folder, which is represented by a dot (`.`), it returns `$False`.
+
 ```powershell
 Split-Path -Path ".\My Pictures\*.jpg" -IsAbsolute
 ```
@@ -123,18 +142,15 @@ Split-Path -Path ".\My Pictures\*.jpg" -IsAbsolute
 False
 ```
 
-This command determines whether the path is relative or absolute. In this case, because the path is
-relative to the current folder, which is represented by a dot (`.`), it returns `$False`.
-
 ### Example 5: Change location to a specified path
 
+This command changes your location to the folder that contains the PowerShell profile.
+
 ```powershell
 PS C:\> Set-Location (Split-Path -Path $profile)
-PS C:\Documents and Settings\User01\My Documents\WindowsPowerShell>
+PS C:\Users\User01\Documents\PowerShell>
 ```
 
-This command changes your location to the folder that contains the PowerShell profile.
-
 The command in parentheses uses `Split-Path` to return only the parent of the path stored in the
 built-in `$Profile` variable. The **Parent** parameter is the default split location parameter.
 Therefore, you can omit it from the command. The parentheses direct PowerShell to run the command
@@ -143,11 +159,11 @@ first. This is a useful way to move to a folder that has a long path name.
 ### Example 6: Split a path using the pipeline
 
 ```powershell
-'C:\Documents and Settings\User01\My Documents\My Pictures' | Split-Path
+'C:\Users\User01\My Documents\My Pictures' | Split-Path
 ```
 
 ```Output
-C:\Documents and Settings\User01\My Documents
+C:\Users\User01\My Documents
 ```
 
 This command uses a pipeline operator (`|`) to send a path to `Split-Path`. The path is enclosed in
@@ -176,9 +192,9 @@ Accept wildcard characters: False
 
 ### -IsAbsolute
 
-Indicates that this cmdlet returns `$True` if the path is absolute and `$False` if it's relative. An
-absolute path has a length greater than zero and doesn't use a dot (`.`) to indicate the current
-path.
+Indicates that this cmdlet returns `$True` if the path is absolute and `$False` if it's relative. On
+Windows, an absolute path string must start with a provider drive specifier, like `C:` or `HKCU:`. A
+relative path starts with a dot (`.`) or a dot-dot (`..`).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -194,8 +210,8 @@ Accept wildcard characters: False
 
 ### -Leaf
 
-Indicates that this cmdlet returns only the last item or container in the path. For example, in the
-path `C:\Test\Logs\Pass1.log`, it returns only `Pass1.log`.
+When using the **Leaf** parameter, `Split-Path` returns only the last item in the path string
+supplied, regardless whether that item is a file or a directory.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -248,9 +264,8 @@ Accept wildcard characters: False
 
 ### -Parent
 
-Indicates that this cmdlet returns only the parent containers of the item or of the container
-specified by the path. For example, in the path `C:\Test\Logs\Pass1.log`, it returns `C:\Test\Logs`.
-The **Parent** parameter is the default split location parameter.
+`Split-Path` returns only the parent container portion of the path string supplied. If the **Path**
+string doesn't contain a parent container, `Split-Path` returns an empty string.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -372,7 +387,8 @@ When you specify the **IsAbsolute** parameter, this cmdlet returns a **Boolean**
   Registry, and Certificate providers.
 
 - `Split-Path` is designed to work with the data exposed by any provider. To list the providers
-  available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
+  available in your session, type `Get-PSProvider`. For more information, see
+  [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
 
 ## RELATED LINKS
 

reference/7.2/Microsoft.PowerShell.Management/Split-Path.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 09/20/2023
+ms.date: 09/03/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/split-path?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Split-Path
@@ -73,9 +73,11 @@ Split-Path -LiteralPath <String[]> [-Resolve] [-Credential <PSCredential>] [<Com
 
 The `Split-Path` cmdlet returns only the specified part of a path, such as the parent folder, a
 subfolder, or a filename. It can also get items that are referenced by the split path and tell
-whether the path is relative or absolute.
+whether the path is relative or absolute. If you split a path without specifying any other
+parameters, `Split-Path` returs the parent part of the path provided.
 
-You can use this cmdlet to get or submit only a selected part of a path.
+The `Split-Path` command returns strings. It doesn't return **FileInfo** or other item objects like
+the `*-Item` commands do.
 
 ## EXAMPLES
 
@@ -91,42 +93,61 @@ HKCU:
 
 This command returns only the qualifier of the path. The qualifier is the drive.
 
-### Example 2: Display filenames
+### Example 2: Display filename portion of the path
+
+When using the **Leaf** parameter, `Split-Path` returns only the last item in the path string
+supplied, regardless whether that item is a file or a directory.
 
 ```powershell
-Split-Path -Path "C:\Test\Logs\*.log" -Leaf -Resolve
+Split-Path -Path .\folder1\*.txt -Leaf
 ```
 
 ```Output
-Pass1.log
-Pass2.log
-...
+*.txt
 ```
 
-This command displays the files that are referenced by the split path. Because this path is split to
-the last item, also known as the leaf, the command displays only the filenames.
+```powershell
+Split-Path -Path .\folder1\*.txt -Leaf -Resolve
+```
 
-The **Resolve** parameter tells `Split-Path` to display the items that the split path references,
-instead of displaying the split path.
+```Output
+file1.txt
+file2.txt
+```
 
-Like all `Split-Path` commands, this command returns strings. It doesn't return **FileInfo** objects
-that represent the files.
+When you use the **Resolve** parameter, `Split-Path` resolves the path string provided and returns
+the items referenced by the path.
 
 ### Example 3: Get the parent container
 
+When using the **Parent** parameter, `Split-Path` returns only the parent container portion of the
+path string supplied. If the **Path** string doesn't contain a parent container, `Split-Path`
+returns an empty string.
+
+```powershell
+Split-Path -Path .\folder1\file1.txt -Parent
+```
+
+```Output
+.\folder1
+```
+
 ```powershell
-Split-Path -Parent "C:\WINDOWS\system32\WindowsPowerShell\V1.0\about_*.txt"
+Split-Path -Path .\folder1\file1.txt -Parent -Resolve
 ```
 
 ```Output
-C:\WINDOWS\system32\WindowsPowerShell\V1.0
+D:\temp\test\folder1
 ```
 
-This command returns only the parent containers of the path. Because it doesn't include any
-parameters to specify the split, `Split-Path` uses the split location default, which is **Parent**.
+When you use the **Resolve** parameter, `Split-Path` resolves the path string provided and returns
+the full path of the parent container.
 
 ### Example 4: Determines whether a path is absolute
 
+This command determines whether the path is relative or absolute. In this case, because the path is
+relative to the current folder, which is represented by a dot (`.`), it returns `$False`.
+
 ```powershell
 Split-Path -Path ".\My Pictures\*.jpg" -IsAbsolute
 ```
@@ -135,18 +156,15 @@ Split-Path -Path ".\My Pictures\*.jpg" -IsAbsolute
 False
 ```
 
-This command determines whether the path is relative or absolute. In this case, because the path is
-relative to the current folder, which is represented by a dot (`.`), it returns `$False`.
-
 ### Example 5: Change location to a specified path
 
+This command changes your location to the folder that contains the PowerShell profile.
+
 ```powershell
 PS C:\> Set-Location (Split-Path -Path $profile)
-PS C:\Documents and Settings\User01\My Documents\WindowsPowerShell>
+PS C:\Users\User01\Documents\PowerShell>
 ```
 
-This command changes your location to the folder that contains the PowerShell profile.
-
 The command in parentheses uses `Split-Path` to return only the parent of the path stored in the
 built-in `$Profile` variable. The **Parent** parameter is the default split location parameter.
 Therefore, you can omit it from the command. The parentheses direct PowerShell to run the command
@@ -155,11 +173,11 @@ first. This is a useful way to move to a folder that has a long path name.
 ### Example 6: Split a path using the pipeline
 
 ```powershell
-'C:\Documents and Settings\User01\My Documents\My Pictures' | Split-Path
+'C:\Users\User01\My Documents\My Pictures' | Split-Path
 ```
 
 ```Output
-C:\Documents and Settings\User01\My Documents
+C:\Users\User01\My Documents
 ```
 
 This command uses a pipeline operator (`|`) to send a path to `Split-Path`. The path is enclosed in
@@ -207,9 +225,9 @@ Accept wildcard characters: False
 
 ### -IsAbsolute
 
-Indicates that this cmdlet returns `$True` if the path is absolute and `$False` if it's relative. An
-absolute path has a length greater than zero and doesn't use a dot (`.`) to indicate the current
-path.
+Indicates that this cmdlet returns `$True` if the path is absolute and `$False` if it's relative. On
+Windows, an absolute path string must start with a provider drive specifier, like `C:` or `HKCU:`. A
+relative path starts with a dot (`.`) or a dot-dot (`..`).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -225,8 +243,8 @@ Accept wildcard characters: False
 
 ### -Leaf
 
-Indicates that this cmdlet returns only the last item or container in the path. For example, in the
-path `C:\Test\Logs\Pass1.log`, it returns only `Pass1.log`.
+When using the **Leaf** parameter, `Split-Path` returns only the last item in the path string
+supplied, regardless whether that item is a file or a directory.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -298,9 +316,8 @@ Accept wildcard characters: False
 
 ### -Parent
 
-Indicates that this cmdlet returns only the parent containers of the item or of the container
-specified by the path. For example, in the path `C:\Test\Logs\Pass1.log`, it returns `C:\Test\Logs`.
-The **Parent** parameter is the default split location parameter.
+`Split-Path` returns only the parent container portion of the path string supplied. If the **Path**
+string doesn't contain a parent container, `Split-Path` returns an empty string.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -405,7 +422,8 @@ When you specify the **IsAbsolute** parameter, this cmdlet returns a **Boolean**
   Registry, and Certificate providers.
 
 - `Split-Path` is designed to work with the data exposed by any provider. To list the providers
-  available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
+  available in your session, type `Get-PSProvider`. For more information, see
+  [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
 
 ## RELATED LINKS