Fix reading/writing syntax parameters in Maml help

src/Common/YamlUtils.cs

@@ -646,8 +646,6 @@ private static List<SyntaxItem> GetSyntaxFromDictionary(OrderedDictionary dictio
                         }
                     }
 
-                    // add the parameter name
-                    si.Parameters.ForEach(p => si.AddParameter(p));
                     syntaxes.Add(si);
                 }
             }

src/MamlWriter/DataType.cs

@@ -16,7 +16,7 @@ public class DataType
         /// <summary>
         ///     The data-type name.
         /// </summary>
-        [XmlElement("name", Namespace = Constants.XmlNamespace.Dev, Order = 0)]
+        [XmlElement("name", Namespace = Constants.XmlNamespace.MAML, Order = 0)]
         public string Name { get; set; } = string.Empty;
 
         /// <summary>

src/MamlWriter/MamlHelpers.cs

@@ -86,7 +86,7 @@ public static Command ConvertCommandHelpToMamlCommand(CommandHelp commandHelp)
             {
                 foreach (var syntax in commandHelp.Syntax)
                 {
-                    command.Syntax.Add(ConvertSyntax(syntax));
+                    command.Syntax.Add(ConvertSyntax(syntax, commandHelp.Parameters));
                 }
             }
 
@@ -142,7 +142,7 @@ private static IEnumerable<CommandValue> ConvertInputOutput(List<Model.InputOutp
             }
         }
 
-        private static SyntaxItem ConvertSyntax(Model.SyntaxItem syntax)
+        private static SyntaxItem ConvertSyntax(Model.SyntaxItem syntax, List<Model.Parameter> parameters)
         {
             var newSyntax = new SyntaxItem();
             var firstSpace = syntax.CommandName.IndexOf(' ');
@@ -154,10 +154,8 @@ private static SyntaxItem ConvertSyntax(Model.SyntaxItem syntax)
             {
                 newSyntax.CommandName = syntax.CommandName.Substring(0, firstSpace);
             }
-            foreach(var parameter in syntax.GetParametersInOrder())
-            {
-                newSyntax.Parameters.Add(ConvertParameter(parameter));
-            }
+            syntax.SortParameters();
+            newSyntax.Parameters.AddRange(syntax.SyntaxParameters.Select(sp => ConvertSyntaxParameter(sp, parameters)));
 
             return newSyntax;
         }
@@ -169,16 +167,22 @@ private static PipelineInputType GetPipelineInputType(Model.Parameter parameter)
             return pipelineInput;
         }
 
-        private static ParameterValue GetParameterValue(Model.Parameter parameter)
+        private static ParameterValue? GetParameterValue(Model.Parameter parameter)
         {
+            // dont render <command:parameterValue> element when the parameter type is SwitchParameter
+            if (parameter.Type is "SwitchParameter" or "System.Management.Automation.SwitchParameter")
+            {
+                return null;
+            }
+
             var parameterValue = new ParameterValue();
             if (parameter is not null)
             {
                 parameterValue.DataType = parameter.Type;
                 parameterValue.IsVariableLength = parameter.VariableLength;
-                // We just mark mandatory if one of the parameter sets is mandatory since MAML doesn't
-                // have a way to disambiguate these.
-                parameterValue.IsMandatory = parameter.ParameterSets.Any(x => x.IsRequired);
+                // Should be `true`. This indicates not the parameter is mandatory or not, but the parameter **value** is mandatory or not.
+                // The parameter which parameter value is not required is SwitchParameter, but SwitchParameter does not ouput this element itself.
+                parameterValue.IsMandatory = true;
             }
             return parameterValue;
         }
@@ -192,6 +196,7 @@ private static Parameter ConvertParameter(Model.Parameter parameter)
             var pSet = parameter.ParameterSets.FirstOrDefault();
             newParameter.Position = pSet is null ? Model.Constants.NamedString : pSet.Position;
             newParameter.Value = GetParameterValue(parameter);
+            newParameter.Type = new DataType() { Name = parameter.Type };
 
             if (parameter.Description is not null)
             {
@@ -201,6 +206,61 @@ private static Parameter ConvertParameter(Model.Parameter parameter)
                 }
             }
 
+            if (parameter.Aliases.Count > 0)
+            {
+                newParameter.Aliases = string.Join(", ", parameter.Aliases);
+            }
+
+            if (parameter.AcceptedValues.Count > 0)
+            {
+                var acceptedValues = parameter.AcceptedValues.Select(val => new ParameterValue() { DataType = val });
+                newParameter.ParameterValueGroup = acceptedValues.ToList();
+            }
+
+            return newParameter;
+        }
+
+        private static Parameter ConvertSyntaxParameter(Model.SyntaxParameter syntaxParam, List<Model.Parameter> parameters)
+        {
+            var newParameter = new MAML.Parameter()
+            {
+                Name = syntaxParam.ParameterName,
+                IsMandatory = syntaxParam.IsMandatory,
+                Position = syntaxParam.Position,
+            };
+            if (syntaxParam.IsSwitchParameter)
+            {
+                newParameter.Type = new DataType()
+                {
+                    Name = "System.Management.Automation.SwitchParameter"
+                };
+            }
+            else
+            {
+                newParameter.Value = new MAML.ParameterValue()
+                {
+                    DataType = syntaxParam.ParameterType,
+                    IsMandatory = true
+                };
+
+                var parameter = parameters.FirstOrDefault(p => string.Equals(p.Name, syntaxParam.ParameterName, StringComparison.Ordinal));
+                if (parameter is not null)
+                {
+                    newParameter.Type = new DataType()
+                    {
+                        Name = parameter.Type
+                    };
+                    if (parameter.Aliases.Count > 0)
+                    {
+                        newParameter.Aliases = string.Join(", ", parameter.Aliases);
+                    }
+                    if (parameter.AcceptedValues.Count > 0)
+                    {
+                        var acceptedValues = parameter.AcceptedValues.Select(val => new ParameterValue() { DataType = val });
+                        newParameter.ParameterValueGroup = acceptedValues.ToList();
+                    }
+                }
+            }
             return newParameter;
         }
 

src/MamlWriter/Parameter.cs

@@ -25,11 +25,21 @@ public class Parameter
         [XmlArrayItem("para", Namespace = Constants.XmlNamespace.MAML)]
         public List<string> Description { get; set; } = new List<string>();
 
+        /// <summary>
+        ///     The parameter value group information ("command:parameterValueGroup").
+        /// </summary>
+        [XmlArray("parameterValueGroup", Namespace = Constants.XmlNamespace.Command, Order = 2)]
+        [XmlArrayItem("parameterValue", Namespace = Constants.XmlNamespace.Command)]
+        public List<ParameterValue>? ParameterValueGroup { get; set; }
+
         /// <summary>
         ///     The parameter value information ("command:parameterValue").
         /// </summary>
-        [XmlElement("parameterValue", Namespace = Constants.XmlNamespace.Command, Order = 2)]
-        public ParameterValue Value { get; set; } = new ParameterValue();
+        [XmlElement("parameterValue", Namespace = Constants.XmlNamespace.Command, Order = 3)]
+        public ParameterValue? Value { get; set; }
+
+        [XmlElement("type", Namespace = Constants.XmlNamespace.Dev, Order = 4)]
+        public DataType? Type { get; set; }
 
         /// <summary>
         ///     Is the parameter mandatory?

src/MarkdownReader/CommandHelpMarkdownReader.cs

@@ -256,6 +256,7 @@ internal static CommandHelp GetCommandHelpFromMarkdown(ParsedMarkdownContent mar
             {
                 syntaxDiagnostics.ForEach(d => commandHelp.Diagnostics.TryAddDiagnostic(d));
             }
+            commandHelp.Syntax.ForEach(si => si.HasCmdletBinding = commandHelp.HasCmdletBinding);
 
             List<DiagnosticMessage> aliasesDiagnostics = new();
             bool aliasHeaderFound = false;

src/Model/CommandHelp.cs

@@ -202,34 +202,6 @@ internal void AddExampleItemRange(IEnumerable<Example> example)
         internal void AddParameter(Parameter parameter)
         {
             Parameters.Add(parameter);
-            foreach(var parameterSet in parameter.ParameterSets)
-            {
-                if (string.Compare(parameterSet.Name, "(All)", StringComparison.OrdinalIgnoreCase) == 0)
-                {
-                    foreach(var syntax in SyntaxDictionary.Values)
-                    {
-                        try
-                        {
-                            syntax.AddParameter(parameter);
-                        }
-                        catch
-                        {
-                            // This is okay, we just don't want to add it to the syntax item if it's already there.
-                        }
-                    }
-                }
-                else if (SyntaxDictionary.TryGetValue(parameterSet.Name, out var syntaxItem))
-                {
-                    try
-                    {
-                        syntaxItem.AddParameter(parameter);
-                    }
-                    catch
-                    {
-                        // This is okay, we just don't want to add it to the syntax item if it's already there.
-                    }
-                }
-            }
         }
 
         public bool TryGetParameter(string name, out Parameter? parameter)

src/Model/SyntaxItem.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Collections.ObjectModel;
 using System.Linq;
 using System.Text;
 
@@ -20,38 +19,13 @@ public class SyntaxItem : IEquatable<SyntaxItem>
 
         public List<SyntaxParameter> SyntaxParameters = new();
 
-        public List<Parameter> Parameters = new();
-
-        private List<string> _parameterNames = new();
-
-        public ReadOnlyCollection<string> ParameterNames {
-            get => new ReadOnlyCollection<string>(_parameterNames);
-        }
-
-        public ReadOnlyCollection<int> PositionalParameterKeys {
-            get => new ReadOnlyCollection<int>(_positionalParameters.Keys);
-        }
-
-        // Sort parameters by position
-        private SortedList<int, Parameter> _positionalParameters;
-
-        // Sort parameters by if they are Required by name
-        private SortedList<string, Parameter> _requiredParameters;
-
-        // Sort parameters by name
-        private SortedList<string, Parameter> _alphabeticOrderParameters;
-
         public bool IsDefaultParameterSet { get; }
 
         public SyntaxItem(string commandName, string parameterSetName, bool isDefaultParameterSet)
         {
             CommandName = commandName;
             ParameterSetName = parameterSetName;
             IsDefaultParameterSet = isDefaultParameterSet;
-
-            _positionalParameters = new SortedList<int, Parameter>();
-            _requiredParameters = new SortedList<string, Parameter>();
-            _alphabeticOrderParameters = new SortedList<string, Parameter>();
         }
 
         /// <summary>
@@ -65,26 +39,6 @@ public SyntaxItem(SyntaxItem syntaxItem)
             IsDefaultParameterSet = syntaxItem.IsDefaultParameterSet;
             SyntaxParameters = new List<SyntaxParameter>(syntaxItem.SyntaxParameters);
             HasCmdletBinding = syntaxItem.HasCmdletBinding;
-            Parameters = new List<Parameter>(syntaxItem.Parameters);
-
-            _positionalParameters = new SortedList<int, Parameter>(syntaxItem._positionalParameters);
-            _requiredParameters = new SortedList<string, Parameter>(syntaxItem._requiredParameters);
-            _alphabeticOrderParameters = new SortedList<string, Parameter>(syntaxItem._alphabeticOrderParameters);
-            _parameterNames = new List<string>(syntaxItem._parameterNames);
-        }
-
-        public void AddParameter(Parameter parameter)
-        {
-            string name = parameter.Name;
-
-            if (Constants.CommonParametersNames.Contains(name))
-            {
-                HasCmdletBinding = true;
-                return;
-            }
-
-            _parameterNames.Add(name);
-            _alphabeticOrderParameters.Add(name, parameter);
         }
 
         /// <summary>
@@ -130,19 +84,6 @@ public void SortParameters()
             SyntaxParameters = sortedList;
         }
 
-        public void AddParameter(SyntaxParameter parameter)
-        {
-            string name = parameter.ParameterName;
-
-            if (Constants.CommonParametersNames.Contains(name))
-            {
-                HasCmdletBinding = true;
-                return;
-            }
-
-            _parameterNames.Add(name);
-        }
-
         private string GetFormattedSyntaxParameter(string paramName, string paramTypeName, bool isPositional, bool isRequired)
         {
             bool isSwitchParam = string.Equals(paramTypeName, "SwitchParameter", StringComparison.OrdinalIgnoreCase);
@@ -183,24 +124,6 @@ private string GetFormattedSyntaxParameter(string paramName, string paramTypeNam
             }
         }
 
-        public IEnumerable<Parameter> GetParametersInOrder()
-        {
-            foreach (KeyValuePair<int, Parameter> kv in _positionalParameters)
-            {
-                yield return kv.Value;
-            }
-
-            foreach (KeyValuePair<string, Parameter> kv in _requiredParameters)
-            {
-                yield return kv.Value;
-            }
-
-            foreach (KeyValuePair<string, Parameter> kv in _alphabeticOrderParameters)
-            {
-                yield return kv.Value;
-            }
-        }
-
         /// <summary>
         /// This emits the command and parameters as if they were returned by Get-Command -syntax
         /// </summary>

src/Transform/TransformBase.cs

@@ -376,8 +376,6 @@ protected IEnumerable<SyntaxItem> GetSyntaxItem(CommandInfo? cmdletInfo, dynamic
                                 string.Compare(paramInfo.ParameterType.Name, "SwitchParameter", true) == 0)
                         );
                     }
-                    Parameter param = GetParameterInfo(cmdletInfo, helpItem, paramInfo);
-                    syn.AddParameter(param);
                 }
 
                 // now take the named parameters.
@@ -393,8 +391,6 @@ protected IEnumerable<SyntaxItem> GetSyntaxItem(CommandInfo? cmdletInfo, dynamic
                             string.Compare(paramInfo.ParameterType.Name, "SwitchParameter", true) == 0);
                         syn.SyntaxParameters.Add(sParm);
                     }
-                    Parameter param = GetParameterInfo(cmdletInfo, helpItem, paramInfo);
-                    syn.AddParameter(param);
                 }
 
                 syntaxItems.Add(syn);