Confirm and WhatIf parameters should have constant descriptions (#768)

Author: adityapatwardhan

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(List<Parameter>fromHelp, List<Parame
                     var dm = new DiagnosticMessage(DiagnosticMessageSource.Merge, $"updating {pName}.", DiagnosticSeverity.Information, "TryGetMergedParameters", -1);
                     diagnosticMessages.Add(dm);
 
-                    var checkTemplate = string.Format(Constants.FillInParameterDescriptionTemplate, helpParam.Name);
+                    var checkTemplate = TransformUtils.GetParameterTemplateString(helpParam.Name);
 
                     var description = helpParam.Description;
 

src/Model/Constants.cs

@@ -6,6 +6,7 @@
 using System.Text;
 using System.Linq;
 using System.IO;
+using System.Runtime.CompilerServices;
 
 namespace Microsoft.PowerShell.PlatyPS.Model
 {
@@ -84,6 +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 = "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.

src/Transform/TransformBase.cs

@@ -236,7 +236,7 @@ protected IEnumerable<Parameter> 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();

src/Transform/TransformUtils.cs

@@ -15,7 +15,7 @@
 
 namespace Microsoft.PowerShell.PlatyPS
 {
-    public class TranformUtils
+    public class TransformUtils
     {
         private static Dictionary<string, string> TypeAbbreviations = new Dictionary<string, string> {
             { "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);
+            }
+        }
     }
 }

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 '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.'
+        }
+    }
 }