From f34ac7069191e23a8301a46b5076d153332a247b Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Mon, 14 Jul 2025 18:02:34 -0700 Subject: [PATCH 1/3] Confirm and WhatIf parameters should have constant descriptions --- src/Common/MergeUtils.cs | 3 ++- src/Model/Constants.cs | 3 +++ src/Transform/TransformBase.cs | 6 +++--- src/Transform/TransformUtils.cs | 23 ++++++++++++++++++++++- 4 files changed, 30 insertions(+), 5 deletions(-) diff --git a/src/Common/MergeUtils.cs b/src/Common/MergeUtils.cs index 004afb64..211445b1 100644 --- a/src/Common/MergeUtils.cs +++ b/src/Common/MergeUtils.cs @@ -3,6 +3,7 @@ using System; using System.Collections.Generic; +using System.ComponentModel; using System.Linq; using Microsoft.PowerShell.PlatyPS.Model; @@ -238,7 +239,7 @@ internal static bool TryGetMergedParameters(ListfromHelp, List GetParameters(CommandInfo cmdletInfo, dynamic? string descriptionFromHelp = GetParameterDescriptionFromHelp(helpItem, param.Name) ?? param.HelpMessage ?? string.Empty; param.Description = string.IsNullOrEmpty(descriptionFromHelp) ? - string.Format(Constants.FillInParameterDescriptionTemplate, param.Name) : + TransformUtils.GetParameterTemplateString(param.Name) : descriptionFromHelp.Trim(); parameters.Add(param); @@ -517,7 +517,7 @@ private string GetAbbreviatedType(Type type) } else { - if (TranformUtils.TryGetTypeAbbreviation(type.FullName, out string abbreviation)) + if (TransformUtils.TryGetTypeAbbreviation(type.FullName, out string abbreviation)) { return abbreviation; } @@ -613,7 +613,7 @@ protected Parameter GetParameterInfo(CommandInfo? cmdletInfo, dynamic? helpItem, string descriptionFromHelp = GetParameterDescriptionFromHelp(helpItem, param.Name) ?? paramAttribInfo.HelpMessage ?? string.Empty; param.Description = string.IsNullOrEmpty(descriptionFromHelp) ? - string.Format(Constants.FillInParameterDescriptionTemplate, param.Name) : + TransformUtils.GetParameterTemplateString(param.Name) : descriptionFromHelp; param.Aliases = paramInfo.Aliases.ToList(); diff --git a/src/Transform/TransformUtils.cs b/src/Transform/TransformUtils.cs index e89081a7..05a7e9b6 100644 --- a/src/Transform/TransformUtils.cs +++ b/src/Transform/TransformUtils.cs @@ -15,7 +15,7 @@ namespace Microsoft.PowerShell.PlatyPS { - public class TranformUtils + public class TransformUtils { private static Dictionary TypeAbbreviations = new Dictionary { { "System.Management.Automation.AliasAttribute" , "Alias" }, @@ -123,5 +123,26 @@ public static bool TryGetTypeAbbreviation(string fullName, out string abbreviati return false; } + + public static string GetParameterTemplateString(string paramName) + { + if (string.IsNullOrEmpty(paramName)) + { + throw new ArgumentException("Parameter name cannot be null or empty.", nameof(paramName)); + } + + if (string.Equals(paramName, "Confirm", StringComparison.OrdinalIgnoreCase)) + { + return Constants.ConfirmParameterDescription; + } + else if (string.Equals(paramName, "WhatIf", StringComparison.OrdinalIgnoreCase)) + { + return Constants.WhatIfParameterDescription; + } + else + { + return string.Format(Constants.FillInParameterDescriptionTemplate, paramName); + } + } } } \ No newline at end of file From 0affbe9e103e13648579d8deb920fc8ffac94051 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Mon, 14 Jul 2025 18:24:23 -0700 Subject: [PATCH 2/3] Add test --- test/Pester/NewMarkdownHelp.Tests.ps1 | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/test/Pester/NewMarkdownHelp.Tests.ps1 b/test/Pester/NewMarkdownHelp.Tests.ps1 index dcb453b1..ca46afdd 100644 --- a/test/Pester/NewMarkdownHelp.Tests.ps1 +++ b/test/Pester/NewMarkdownHelp.Tests.ps1 @@ -638,4 +638,23 @@ Write-Host 'Hello World!' $file | Should -FileContentMatch 'SupportsWildcards: true' } } + + Context 'Confirm Whatif description' { + BeforeAll { + function global:Test-ConfirmWhatIfDescription { + [CmdletBinding(SupportsShouldProcess = $true)] + param ( + [Parameter()] + [string] $Name + ) + } + + $file = New-MarkdownCommandHelp -Command (Get-Command 'Test-ConfirmWhatIfDescription') -OutputFolder "$TestDrive/NewMarkDownHelp" + } + + It 'should have a description for Confirm and WhatIf parameters' { + $file | Should -FileContentMatch '### -Confirm' + $file | Should -FileContentMatch '### -WhatIf' + } + } } From b53e54fcd41e306d12bbe74a216ac09515d7610f Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Mon, 14 Jul 2025 18:36:59 -0700 Subject: [PATCH 3/3] Update with correct strings --- src/Model/Constants.cs | 4 ++-- test/Pester/NewMarkdownHelp.Tests.ps1 | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Model/Constants.cs b/src/Model/Constants.cs index b4ec7824..43f19fd7 100644 --- a/src/Model/Constants.cs +++ b/src/Model/Constants.cs @@ -85,8 +85,8 @@ internal static partial class Constants internal const string FillInGuid = "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; internal const string LocaleEnUs = "en-US"; internal const string skippingMessageFmt = "'{0}' exists, skipping. Use -Force to overwrite."; - internal const string ConfirmParameterDescription = "{{ Fill Confirm Description }}"; - internal const string WhatIfParameterDescription = "{{ Fill WhatIf Description }}"; + internal const string ConfirmParameterDescription = "Prompts you for confirmation before running the cmdlet."; + internal const string WhatIfParameterDescription = "Tells PowerShell to run the command in a mode that only reports what would happen, but not actually let the command run or make changes."; // TODO: ProgressAction is not a common parameter for all versions of PowerShell. // This should not be added under all circumstances. diff --git a/test/Pester/NewMarkdownHelp.Tests.ps1 b/test/Pester/NewMarkdownHelp.Tests.ps1 index ca46afdd..85815b77 100644 --- a/test/Pester/NewMarkdownHelp.Tests.ps1 +++ b/test/Pester/NewMarkdownHelp.Tests.ps1 @@ -653,8 +653,8 @@ Write-Host 'Hello World!' } It 'should have a description for Confirm and WhatIf parameters' { - $file | Should -FileContentMatch '### -Confirm' - $file | Should -FileContentMatch '### -WhatIf' + $file | Should -FileContentMatch 'Prompts you for confirmation before running the cmdlet.' + $file | Should -FileContentMatch 'Tells PowerShell to run the command in a mode that only reports what would happen, but not actually let the command run or make changes.' } } }