sorting parameters by position then by required and then by name in syntax generation

XmlDoc2CmdletDoc.Core/Engine.cs

@@ -324,7 +324,9 @@ private XElement GenerateSyntaxItemElement(ICommentReader commentReader, Command
         {
             var syntaxItemElement = new XElement(CommandNs + "syntaxItem",
                                                  new XElement(MamlNs + "name", command.Name));
-            foreach (var parameter in command.GetParameters(parameterSetName))
+            foreach (var parameter in command.GetParameters(parameterSetName).OrderBy(p => p.GetPosition(parameterSetName)).
+                                                                              ThenBy(p => p.IsRequired(parameterSetName) ? "0" : "1").
+                                                                              ThenBy(p => p.Name))
             {
                 syntaxItemElement.Add(GenerateComment("Parameter: " + parameter.Name));
                 syntaxItemElement.Add(GenerateParameterElement(commentReader, parameter, parameterSetName, reportWarning));

XmlDoc2CmdletDoc.TestModule/PositionedParameters/TestPositionedParametersCommand.cs

@@ -0,0 +1,48 @@
+using System.Management.Automation;
+
+namespace XmlDoc2CmdletDoc.TestModule.PositionedParameters
+{
+    /// <summary>
+    /// <para type="synopsis">This is part of the Test-PositionedParameters synopsis.</para>
+    /// <para type="description">This is part of the Test-PositionedParameters description.</para>
+    /// </summary>
+    [Cmdlet(VerbsDiagnostic.Test, "PositionedParameters")]
+    public class TestPositionedParametersCommand : Cmdlet
+    {
+        /// <summary>
+        /// <para type="description">This is part of the ParameterA description.</para>
+        /// </summary>
+        [Parameter(Position = 3)]
+        public string ParameterA { get; set; }
+
+        /// <summary>
+        /// <para type="description">This is part of the ParameterB description.</para>
+        /// </summary>
+        [Parameter(Position = 2)]
+        public string ParameterB { get; set; }
+
+        /// <summary>
+        /// <para type="description">This is part of the ParameterC description.</para>
+        /// </summary>
+        [Parameter(Position = 0)]
+        public string ParameterC { get; set; }
+
+        /// <summary>
+        /// <para type="description">This is part of the ParameterD description.</para>
+        /// </summary>
+        [Parameter(Position = 1)]
+        public string ParameterD { get; set; }
+
+        /// <summary>
+        /// <para type="description">This is part of the ParameterE description.</para>
+        /// </summary>
+        [Parameter]
+        public string ParameterE { get; set; }
+
+        /// <summary>
+        /// <para type="description">This is part of the ParameterF description.</para>
+        /// </summary>
+        [Parameter(Mandatory = true)]
+        public string ParameterF { get; set; }
+    }
+}

XmlDoc2CmdletDoc.TestModule/XmlDoc2CmdletDoc.TestModule.csproj

@@ -47,6 +47,7 @@
     <Compile Include="Maml\TestMamlElementsCommand.cs" />
     <Compile Include="Manual\ManualClass.cs" />
     <Compile Include="Manual\TestManualElementsCommand.cs" />
+    <Compile Include="PositionedParameters\TestPositionedParametersCommand.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="InputTypes\InputTypeClass.cs" />
     <Compile Include="References\TestReferencesCommand.cs" />

XmlDoc2CmdletDoc.Tests/AcceptanceTests.cs

@@ -38,6 +38,7 @@ static AcceptanceTests()
         private XElement testMamlElementsCommandElement;
         private XElement testReferencesCommandElement;
         private XElement testInputTypesCommandElement;
+        private XElement testPositionedParametersCommandElement;
 
         [TestFixtureSetUp]
         public void SetUp()
@@ -67,6 +68,7 @@ public void SetUp()
             testMamlElementsCommandElement = rootElement.XPathSelectElement("command:command[command:details/command:name/text() = 'Test-MamlElements']", resolver);
             testReferencesCommandElement = rootElement.XPathSelectElement("command:command[command:details/command:name/text() = 'Test-References']", resolver);
             testInputTypesCommandElement = rootElement.XPathSelectElement("command:command[command:details/command:name/text() = 'Test-InputTypes']", resolver);
+            testPositionedParametersCommandElement = rootElement.XPathSelectElement("command:command[command:details/command:name/text() = 'Test-PositionedParameters']", resolver);
         }
 
         [Test]
@@ -798,5 +800,38 @@ private void CheckMamlClassType(XElement type, bool expectADescription)
 @"<maml:description xmlns:maml=""http://schemas.microsoft.com/maml/2004/10"">
   <maml:para>This is the MamlClass description.</maml:para>
 </maml:description>";
+
+        [Test]
+        public void Command_Syntax_Parameters_Ordered_By_Position()
+        {
+            Assert.That(testPositionedParametersCommandElement, Is.Not.Null);
+
+            var syntaxItemParameters = testPositionedParametersCommandElement.XPathSelectElements("command:syntax/command:syntaxItem/command:parameter", resolver).ToList();
+
+            Assert.That(syntaxItemParameters, Is.Not.Empty);
+            Assert.That(syntaxItemParameters.Count, Is.EqualTo(6));
+
+            var position = syntaxItemParameters[0].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("0"));
+
+            position = syntaxItemParameters[1].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("1"));
+
+            position = syntaxItemParameters[2].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("2"));
+
+            position = syntaxItemParameters[3].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("3"));
+
+            var require = syntaxItemParameters[4].Attribute("required").Value;
+            position = syntaxItemParameters[4].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("named"));
+            Assert.That(require, Is.EqualTo("true"));
+
+            require = syntaxItemParameters[5].Attribute("required").Value;
+            position = syntaxItemParameters[5].Attribute("position").Value;
+            Assert.That(position, Is.EqualTo("named"));
+            Assert.That(require, Is.EqualTo("false"));
+        }
     }
 }