Updated comment based help (#3)

powershell-module/Az.Tools.Migration/Functions/Public/Find-AzUpgradeCommandReference.ps1

@@ -5,28 +5,29 @@ function Find-AzUpgradeCommandReference
         Searches for AzureRM PowerShell command references in the specified file or folder.
 
     .DESCRIPTION
-        Searches for AzureRM PowerShell command references in the specified file or folder. When reviewing the specified file or folder
-        all of the cmdlets used in the files will be analyzed and compared against known AzureRM PowerShell commands. If commands match a known
+        Searches for AzureRM PowerShell command references in the specified file or folder. When reviewing the specified file or folder, all of the cmdlets used in the files will be analyzed and compared against known AzureRM PowerShell commands. If commands match a known
         AzureRM cmdlet, then output will be returned that shows the position/offset for each usage.
 
         The output of this command can be pipelined into the New-AzUpgradeModulePlan cmdlet to generate a detailed list of required upgrade changes.
 
     .PARAMETER FilePath
-        Specify the path to a single PowerShell file.
+        Specifies the path to a single PowerShell file.
 
     .PARAMETER DirectoryPath
-        Specify the path to the folder where PowerShell scripts or modules reside.
+        Specifies the path to the folder where PowerShell scripts or modules reside.
 
     .PARAMETER AzureRmVersion
-        Specify the AzureRM module version used in your existing PowerShell file(s)/modules.
+        Specifies the AzureRM module version used in your existing PowerShell file(s) or modules.
 
     .EXAMPLE
-        PS C:\> Find-AzUpgradeCommandReference -FilePath "C:\scripts\test.ps1" -AzureRmVersion "6.13.1"
-        Finds AzureRM PowerShell command references in the specified file.
+        The following example finds AzureRM PowerShell command references in the specified file.
+
+        Find-AzUpgradeCommandReference -FilePath 'C:\Scripts\test.ps1' -AzureRmVersion '6.13.1'
 
     .EXAMPLE
-        PS C:\> Find-AzUpgradeCommandReference -DirectoryPath "C:\scripts" -AzureRmVersion "6.13.1"
-        Finds AzureRM PowerShell command references in the specified directory and subfolders.
+        The following example finds AzureRM PowerShell command references in the specified directory and subfolders.
+
+        Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts' -AzureRmVersion '6.13.1'
     #>
     [CmdletBinding()]
     Param

powershell-module/Az.Tools.Migration/Functions/Public/Invoke-AzUpgradeModulePlan.ps1

@@ -2,22 +2,22 @@ function Invoke-AzUpgradeModulePlan
 {
     <#
     .SYNOPSIS
-        Invokes/executes the specified module upgrade plan steps.
+        Invokes the specified module upgrade plan.
 
     .DESCRIPTION
-        Invokes/executes the specified module upgrade plan steps.
+        Invokes the specified module upgrade plan.
 
-        IMPORTANT: This step is destructive and makes file edits according to module upgrade plan. Always ensure that you have
-        a backup copy of the source code in question (for example by using source control). There is no 'undo' operation available after this command runs.
+        IMPORTANT: This step is destructive. It makes file edits according to the module upgrade plan. NOTE: There is no "undo" operation. Always ensure that you have a backup copy of the target PowerShell script or module.
 
         The upgrade plan is generated by running the New-AzUpgradeModulePlan cmdlet.
 
     .PARAMETER Plan
-        Specify the upgrade plan steps to follow. This is usually passed from pipeline input.
+        Specifies the upgrade plan steps to execute. This is usually passed via pipeline input.
 
     .EXAMPLE
-        PS C:\ Find-AzureRmCommandReferences -DirectoryPath 'C:\source\myModule' -AzureRmModuleVersion 6.13.1 | New-AzUpgradeModulePlan -AzModuleVersion 4.2.0 | Invoke-AzUpgradeModulePlan
-        Invokes the upgrade plan generated for "myModule".
+        The following example invokes the upgrade plan for a PowerShell module named "myModule".
+
+        Find-AzUpgradeCommandReference -DirectoryPath 'C:\Source\myModule' -AzureRmVersion 6.13.1 | New-AzUpgradeModulePlan -ToAzVersion 4.4.0 | Invoke-AzUpgradeModulePlan
     #>
     [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "High")]
     Param

powershell-module/Az.Tools.Migration/Functions/Public/New-AzUpgradeModulePlan.ps1

@@ -2,38 +2,40 @@ function New-AzUpgradeModulePlan
 {
     <#
     .SYNOPSIS
-        Generates a new upgrade plan for migrating to the Az module.
+        Generates a new upgrade plan for migrating to the Az PowerShell module.
 
     .DESCRIPTION
-        Generates a new upgrade plan for migrating to the Az module. The upgrade plan details the specific file/offset
-        points that require changes move AzureRM commands to Az commands.
+        Generates a new upgrade plan for migrating to the Az PowerShell module. The upgrade plan details the specific file/offset points that require changes when moving from AzureRM commands to Az commands.
 
     .PARAMETER FromAzureRmVersion
-        Specify the AzureRM module version used in your existing PowerShell file(s)/modules.
+        Specifies the AzureRM module version used in your existing PowerShell scripts(s) or modules.
 
     .PARAMETER ToAzVersion
-        Specify the Az module version to upgrade to.
+        Specifies the Az module version to upgrade to. Currently, only Az version 4.4.0 is supported.
 
     .PARAMETER FilePath
-        Specify the path to a single PowerShell file.
+        Specifies the path to a single PowerShell file.
 
     .PARAMETER DirectoryPath
-        Specify the path to the folder where PowerShell scripts or modules reside.
+        Specifies the path to a folder where PowerShell scripts or modules reside.
 
-    .PARAMETER AzureRmCmdReferences
-        Specify the AzureRM command references collection output from the Find-AzUpgradeCommandReference cmdlet.
+    .PARAMETER AzureRmCmdReference
+        Specifies the AzureRM command references output from the Find-AzUpgradeCommandReference cmdlet.
 
     .EXAMPLE
-        PS C:\ New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.4.0 -FilePath "C:\scripts\my-azure-script.ps1"
-        Generates a new Az module upgrade plan for the script file 'C:\scripts\my-azure-script.ps1'.
+        The following example generates a new Az module upgrade plan for the script file 'C:\Scripts\my-azure-script.ps1'.
+
+        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.4.0 -FilePath 'C:\Scripts\my-azure-script.ps1'
 
     .EXAMPLE
-        PS C:\ New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.4.0 -DirectoryPath "C:\scripts"
-        Generates a new Az module upgrade plan for the script/module files under C:\scripts.
+        The following example generates a new Az module upgrade plan for the script and module files located under C:\Scripts.
+
+        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.4.0 -DirectoryPath 'C:\Scripts'
 
     .EXAMPLE
-        PS C:\ Find-AzUpgradeCommandReference -DirectoryPath "C:\scripts" -AzureRmVersion "6.13.1" | New-AzUpgradeModulePlan -ToAzVersion 4.4.0
-        Generates a new Az module upgrade plan for the script/module files under C:\scripts.
+        The following example generates a new Az module upgrade plan for the script and module files under C:\Scripts.
+
+        Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts' -AzureRmVersion '6.13.1' | New-AzUpgradeModulePlan -ToAzVersion 4.4.0
     #>
     [CmdletBinding()]
     Param