From a466082c5ed5e819f97f82fdc943ecb2ba07484e Mon Sep 17 00:00:00 2001
From: Aditya Patwardhan <adityap@microsoft.com>
Date: Thu, 26 Jun 2025 14:32:56 -0700
Subject: [PATCH] Update the parameter description in markdown when comment
 based help is updated

---
 src/Common/MergeUtils.cs | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/Common/MergeUtils.cs b/src/Common/MergeUtils.cs
index 7e69af93..004afb64 100644
--- a/src/Common/MergeUtils.cs
+++ b/src/Common/MergeUtils.cs
@@ -186,7 +186,7 @@ internal static bool TryGetMergedParameters(List<Parameter>fromHelp, List<Parame
                 var cmdParam = matchingCommandParameter.Count() > 0 ? matchingCommandParameter.First() : null;
                 var foundParams = fromHelp.Where(x => string.Compare(x.Name, pName) == 0);
                 var helpParam = foundParams.Count() > 0 ? foundParams.First() : null;
-                
+
                 // This should never happen, but if it does, we'll log it.
                 if (helpParam is null && cmdParam is null)
                 {
@@ -237,9 +237,25 @@ 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 description = helpParam.Description;
+
+                    if (string.Equals(helpParam.Description, checkTemplate, StringComparison.OrdinalIgnoreCase))
+                    {
+                        diagnosticMessages.Add(new DiagnosticMessage(DiagnosticMessageSource.Merge, $"Parameter {pName} has no description in the help.", DiagnosticSeverity.Warning, "TryGetMergedParameters", -1));
+                        description = cmdParam.Description;
+                    }
+                    else if (!string.Equals(helpParam.Description, cmdParam.Description, StringComparison.OrdinalIgnoreCase))
+                    {
+                        diagnosticMessages.Add(new DiagnosticMessage(DiagnosticMessageSource.Merge, $"Parameter {pName} has the different description in the help and the command. Concatinating.", DiagnosticSeverity.Information, "TryGetMergedParameters", -1));
+                        description = string.Join(Environment.NewLine, helpParam.Description, cmdParam.Description);
+                    }
+
                     var newParameter = new Parameter(cmdParam)
                     {
-                        Description = helpParam.Description,
+                        Description = description,
                         DontShow = helpParam.DontShow,
                         DefaultValue = helpParam.DefaultValue
                     };