Docs fixes and comment-based help for PS scripts

docs/optimization-engine/README.md

@@ -152,7 +152,7 @@ After deploying AOE, there are several ways for you to get started (you have to
 
 1. Open the built-in Power BI report to get deeper insights about recommendations and customize it to your needs. See [Reports](./reports.md) for more details.
 
-1. Customize AOE by widening the scope of the engine or adjusting thresholds to your needs (this can be done right after deployment). For all the available customization details, check [Customizations](./customizing-aoe.md).
+1. Customize AOE by widening the scope of the engine or adjusting thresholds to your needs (this can be done right after deployment). For all the available customization details, check [Customizations](./customize.md).
 
 1. For richer virtual machine right-size recommendations, you can add your machines' performance logs to the scope of AOE. Check [Configuring workspaces](./configuring-workspaces.md).
 

docs/optimization-engine/reports.md

@@ -78,6 +78,8 @@ The **Recommendation Details** option takes you to a page where you can see all
 
 ![Fit score history for a specific recommendation](../assets/images/aoe/powerbi-dashboard-fitscorehistory.jpg "Fit score history for a specific recommendation")
 
+<br>
+
 ## 📒 Workbooks
 
 With AOE's Log Analytics Workbooks, you can explore many perspectives over the data that is collected every day. For example, costs growing anomalies, Microsoft Entra ID and Azure RM principals and roles assigned, how your resources are distributed, or getting insights about your Azure commitments usage (supports only EA and MCA customers). See below a short description of each Workbook.

docs/optimization-engine/setup-options.md

@@ -79,7 +79,7 @@ In order to leverage the Workbooks that allow you to analyze your Azure commitme
 
 If you run into issues with the Azure Pricesheet ingestion (due to the large size of the CVS export), you can create the following Azure Automation variable, to filter in the Price Sheet regions: `AzureOptimization_PriceSheetMeterRegions` set to the comma-separated billing regions of your virtual machines (e.g. *EU West,EU North*).
 
-The Reservations Usage Workbook has a couple of "Unused Reservations" tiles that require AOE to export Consumption data at the EA/MCA scope (instead of the default Subscription scope). You can switch to EA/MCA scope consumption by creating/updating the `AzureOptimization_ConsumptionScope` Automation variable with `BillingAccount` as value. Be aware that this option may generate a very large single consumption export which may lead to errors due to lack of memory (this would in turn require [deploying AOE with a Hybrid Worker](./customizing-aoe.md#-scale-aoe-runbooks-with-hybrid-worker)).
+The Reservations Usage Workbook has a couple of "Unused Reservations" tiles that require AOE to export Consumption data at the EA/MCA scope (instead of the default Subscription scope). You can switch to EA/MCA scope consumption by creating/updating the `AzureOptimization_ConsumptionScope` Automation variable with `BillingAccount` as value. Be aware that this option may generate a very large single consumption export which may lead to errors due to lack of memory (this would in turn require [deploying AOE with a Hybrid Worker](./customize.md#-scale-aoe-runbooks-with-hybrid-worker)).
 
 ## 🔼 Upgrading AOE
 

src/optimization-engine/Deploy-AzureOptimizationEngine.ps1

@@ -1,4 +1,51 @@
-# TODO: Add doc comments
+<#
+.SYNOPSIS
+This script deploys the Azure Optimization Engine.
+
+.DESCRIPTION
+This script deploys the Azure Optimization Engine to an Azure subscription. The script will guide you through the deployment process, allowing you to choose the subscription, 
+resource group, and other deployment settings. The script will also check the availability of the chosen resource names and provide you with the option to reuse an existing 
+Log Analytics Workspace or create a new one.
+
+.PARAMETER TemplateUri
+The URI of the Bicep template to deploy. If not provided, the script will use the default template from the GitHub repository.
+
+.PARAMETER AzureEnvironment
+The Azure environment to deploy the resources to. Default is AzureCloud.
+
+.PARAMETER DoPartialUpgrade
+A switch to indicate if the script should perform a partial upgrade of the existing resources. Default is false.
+
+.PARAMETER IgnoreNamingAvailabilityErrors
+A switch to indicate if the script should ignore SQL Server naming availability errors (when a custom SQL engine is being used). Default is false.
+
+.PARAMETER SilentDeploymentSettingsPath
+The path to the silent deployment settings file. If provided, the script will use the settings from the file to deploy the resources without any user interaction.
+
+.PARAMETER ResourceTags
+A hashtable of resource tags to apply to the deployed resources. Default is an empty hashtable.
+
+.PARAMETER EnableDefaultTelemetry
+A boolean to indicate if the default telemetry should be enabled. Default is true.
+
+.EXAMPLE
+.\Deploy-AzureOptimizationEngine.ps1
+
+Deploys or upgrades the Azure Optimization Engine using the default template from the GitHub repository.
+
+.EXAMPLE
+.\Deploy-AzureOptimizationEngine.ps1 -DoPartialUpgrade
+
+Performs a partial upgrade of the existing resources.
+
+.EXAMPLE
+.\Deploy-AzureOptimizationEngine.ps1 -TemplateUri "https://raw.githubusercontent.com/microsoft/finops-toolkit/dev/src/optimization-engine/azuredeploy.bicep" -AzureEnvironment "AzureChinaCloud" -ResourceTags @{"Environment"="Production"; "Owner"="John Doe"}
+
+Deploys or upgrades the Azure Optimization Engine using a custom template from the GitHub repository, in the AzureChinaCloud environment, with custom resource tags.
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/deployment
+#>
 param (
     [Parameter(Mandatory = $false)]
     [string] $TemplateUri,

src/optimization-engine/Reset-AutomationSchedules.ps1

@@ -1,3 +1,25 @@
+<#
+.SYNOPSIS
+This script resets the Azure Optimization Engine schedules to a new base time and optionally changes the Hybrid Worker Group for all schedules.
+
+.DESCRIPTION
+This script resets the Azure Optimization Engine schedules to a new base time and optionally changes the Hybrid Worker Group for all schedules.
+
+.PARAMETER AzureEnvironment
+The Azure environment to use. Possible values are AzureCloud, AzureChinaCloud, AzureUSGovernment.
+
+.PARAMETER AutomationAccountName
+The name of the Automation Account where the Azure Optimization Engine is deployed.
+
+.PARAMETER ResourceGroupName
+The name of the Resource Group where the Automation Account is located.
+
+.EXAMPLE
+.\Reset-AutomationSchedules.ps1 -AutomationAccountName "MyAutomationAccount" -ResourceGroupName "MyResourceGroup"
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/customize
+#>
 param(
     [Parameter(Mandatory = $false)] 
     [String] $AzureEnvironment = "AzureCloud",

src/optimization-engine/Setup-BenefitsUsageDependencies.ps1

@@ -1,3 +1,27 @@
+<#
+.SYNOPSIS
+This script sets up the necessary dependencies for the Azure Optimization Engine to collect the data required for the several Azure benefits workbooks.
+
+.DESCRIPTION
+This script sets up the necessary dependencies for the Azure Optimization Engine to collect the data required for the several Azure benefits workbooks. 
+It will ask for the customer type (EA or MCA), the billing account ID, the billing profile ID (if MCA), and the consumption currency code. It will then grant 
+the necessary roles to the Azure Optimization Engine managed identity and set up the required variables in the Automation Account.
+
+.PARAMETER AzureEnvironment
+The Azure environment to use. Possible values are AzureCloud, AzureChinaCloud, AzureUSGovernment.
+
+.PARAMETER AutomationAccountName
+The name of the Automation Account where the Azure Optimization Engine is deployed.
+
+.PARAMETER ResourceGroupName
+The name of the Resource Group where the Automation Account is located.
+
+.EXAMPLE
+.\Setup-BenefitsUsageDependencies.ps1 -AutomationAccountName "MyAutomationAccount" -ResourceGroupName "MyResourceGroup"
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/commitmentssetup
+#>
 param(
     [Parameter(Mandatory = $false)] 
     [String] $AzureEnvironment = "AzureCloud",

src/optimization-engine/Setup-DataCollectionRules.ps1

@@ -1,3 +1,29 @@
+<#
+.SYNOPSIS
+Deploys Data Collection Rules (DCRs) to collect performance counters from Windows and Linux virtual machines.
+
+.DESCRIPTION
+This script deploys Data Collection Rules (DCRs) to collect performance counters from Windows and Linux virtual machines required by the Azure Optimization Engine
+to augment the Azure Advisor virtual machine right-size recommendations with guest OS metrics and accurate fit score.
+
+.PARAMETER AzureEnvironment
+The Azure environment to use. Default is AzureCloud.
+
+.PARAMETER DestinationWorkspaceResourceId
+The Resource ID of the destination Log Analytics workspace.
+
+.PARAMETER IntervalSeconds
+The interval in seconds to collect performance counters. Default is 60 seconds.
+
+.PARAMETER ResourceTags
+The tags to apply to the resources created.
+
+.EXAMPLE
+.\Deploy-AzureOptimizationEngine.ps1 -DestinationWorkspaceResourceId "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.OperationalInsights/workspaces/MyWorkspace"
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/customize
+#>
 param(
     [Parameter(Mandatory = $false)] 
     [String] $AzureEnvironment = "AzureCloud",

src/optimization-engine/Setup-LogAnalyticsWorkspaces.ps1

@@ -1,3 +1,31 @@
+<#
+.SYNOPSIS
+This script sets up Log Analytics workspaces for Azure Optimization Engine to collect the required performance counters with 
+the legacy Log Analytics agent (to be deprecated on Aug 31, 2024).
+
+.DESCRIPTION
+This script sets up Log Analytics workspaces for Azure Optimization Engine to collect the required performance counters with
+the legacy Log Analytics agent (to be deprecated on Aug 31, 2024). The script will check if the required performance counters
+are already being collected and will (optionally) automatically fix any missing performance counters.
+
+.PARAMETER AzureEnvironment
+The Azure environment to use. Default is AzureCloud.
+
+.PARAMETER WorkspaceIds
+The workspace IDs to use (use the workspace GUID, not the ARM resource ID). If not specified, all workspaces will be used.
+
+.PARAMETER AutoFix
+Automatically fix missing performance counters.
+
+.PARAMETER IntervalSeconds
+The interval in seconds to collect performance counters.
+
+.EXAMPLE
+.\Setup-LogAnalyticsWorkspaces.ps1 -WorkspaceIds "00000000-0000-0000-0000-000000000001","00000000-0000-0000-0000-000000000002" -AutoFix
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/customize
+#>
 param(
     [Parameter(Mandatory = $false)] 
     [String] $AzureEnvironment = "AzureCloud",

src/optimization-engine/Suppress-Recommendation.ps1

@@ -1,3 +1,20 @@
+<#
+.SYNOPSIS
+This script suppresses a recommendation in the Azure Optimization Engine.
+
+.DESCRIPTION
+This script suppresses a recommendation in the Azure Optimization Engine. The script will prompt the user for the required information
+to suppress the recommendation.
+
+.PARAMETER RecommendationId
+The recommendation Id to suppress.
+
+.EXAMPLE
+.\Suppress-Recommendation.ps1 -RecommendationId "00000000-0000-0000-0000-000000000001"
+
+.LINK
+https://aka.ms/AzureOptimizationEngine/suppressrecs
+#>
 param(
     [Parameter(Mandatory = $true)] 
     [String] $RecommendationId