feat(commandlinehelp): Order parameters in the "Usage" section

In a command's "Usage" section, order the parameters. Positional parameters are ordered by their position, followed by named parameters (required parameters first, then ordered by name) and switch parameters (ordered by name)
ap0llo · Feb 20, 2021 · e51f605 · e51f605
1 parent 14c5ae5
commit e51f605
Show file tree

Hide file tree

Showing 8 changed files with 310 additions and 7 deletions.
diff --git a/docs/demoprojects/commandline/commands/Command1.md b/docs/demoprojects/commandline/commands/Command1.md
@@ -17,9 +17,9 @@ The command page includes the commands description (provided as 'HelpText' on th
 ```txt
 DemoProject Command1 [<VALUE>]
                      [<VALUE>]
+                     --parameter4 <VALUE>
                      [--parameter1 <VALUE>]
                      [--parameter2|-x <VALUE>]
-                     --parameter4 <VALUE>
                      [--parameter5 <VALUE>]
                      [-y <VALUE>]
 ```

diff --git a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs
@@ -232,6 +232,28 @@ public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAuto
             Approve(model, configuration);
         }
 
+        [Fact]
+        public void Command_parameters_are_ordered()
+        {
+            // Expected parameter order:
+            // - Unnamed parameters (ordered by position)
+            // - Required Named parameters (ordered by name)
+            // - Optional Named parameters (ordered by name)
+            // - Switch parameters (ordered by name)            
+
+            var model = m_ApplicationDocumentation
+                .AddCommand("CommandName")
+                    .WithSwitchParameter("B")
+                    .WithSwitchParameter(null, "A")
+                    .WithNamedParameter("paramD", required: true)
+                    .WithNamedParameter("paramA", required: false)
+                    .WithNamedParameter("paramC", required: true)
+                    .WithNamedParameter("paramB", required: false)
+                    .WithPositionalParameter(position: 2)
+                    .WithPositionalParameter(position: 1);
+
+            Approve(model);
+        }
 
         private void Approve(CommandDocumentation model, CommandLineHelpConfiguration? configuration = null)
         {

diff --git a/...ocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs b/...ocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs
@@ -81,6 +81,33 @@ public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAuto
             Approve(application, configuration);
         }
 
+        [Fact]
+        public void Command_parameters_are_ordered()
+        {
+            // Expected parameter order:
+            // - Unnamed parameters (ordered by position)
+            // - Required Named parameters (ordered by name)
+            // - Optional Named parameters (ordered by name)
+            // - Switch parameters (ordered by name)            
+
+            var application = new SingleCommandApplicationDocumentation(name: "TestApp", "1.2.3")
+            {
+                Usage = new[] { "Usage line 1", "Usage line2" }
+            };
+
+            application = application
+                .WithSwitchParameter("B")
+                .WithSwitchParameter(null, "A")
+                .WithNamedParameter("paramD", required: true)
+                .WithNamedParameter("paramA", required: false)
+                .WithNamedParameter("paramC", required: true)
+                .WithNamedParameter("paramB", required: false)
+                .WithPositionalParameter(position: 2)
+                .WithPositionalParameter(position: 1);
+
+            Approve(application);
+        }
+
 
         private void Approve(SingleCommandApplicationDocumentation model, CommandLineHelpConfiguration? configuration = null)
         {

diff --git a/...neHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt b/...neHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt
@@ -0,0 +1,125 @@
+<!--  
+  <auto-generated>   
+    The contents of this file were generated by a tool.  
+    Changes to this file may be list if the file is regenerated  
+  </auto-generated>   
+-->
+
+# `CommandName` Command
+
+**Application:** [TestApp](../index.md)  
+**Version:** 1.2.3
+
+## Usage
+
+```txt
+TestApp CommandName [<VALUE>]
+                    [<VALUE>]
+                    --paramC <VALUE>
+                    --paramD <VALUE>
+                    [--paramA <VALUE>]
+                    [--paramB <VALUE>]
+                    [-A]
+                    [--B]
+```
+
+## Parameters
+
+| Position                   | Name                        | Short Name        | Required | Description |
+| -------------------------- | --------------------------- | ----------------- | -------- | ----------- |
+| [1](#parameter-position-1) |                             |                   | No       |             |
+| [2](#parameter-position-2) |                             |                   | No       |             |
+|                            | [paramA](#parama-parameter) |                   | No       |             |
+|                            | [paramB](#paramb-parameter) |                   | No       |             |
+|                            | [paramC](#paramc-parameter) |                   | Yes      |             |
+|                            | [paramD](#paramd-parameter) |                   | Yes      |             |
+|                            | [B](#b-parameter)           |                   | No       |             |
+|                            |                             | [A](#a-parameter) | No       |             |
+
+### Parameter (Position 1)
+
+|                |        |
+| -------------- | ------ |
+| Position:      | 1      |
+| Required:      | No     |
+| Default value: | *None* |
+
+___
+
+### Parameter (Position 2)
+
+|                |        |
+| -------------- | ------ |
+| Position:      | 2      |
+| Required:      | No     |
+| Default value: | *None* |
+
+___
+
+### `paramA` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramA            |
+| Position:      | *Named parameter* |
+| Required:      | No                |
+| Default value: | *None*            |
+
+___
+
+### `paramB` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramB            |
+| Position:      | *Named parameter* |
+| Required:      | No                |
+| Default value: | *None*            |
+
+___
+
+### `paramC` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramC            |
+| Position:      | *Named parameter* |
+| Required:      | Yes               |
+| Default value: | *None*            |
+
+___
+
+### `paramD` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramD            |
+| Position:      | *Named parameter* |
+| Required:      | Yes               |
+| Default value: | *None*            |
+
+___
+
+### `B` Parameter
+
+|                |                           |
+| -------------- | ------------------------- |
+| Name:          | B                         |
+| Position:      | *None (Switch Parameter)* |
+| Required:      | *No (Switch Parameter)*   |
+| Default value: | `false`                   |
+
+___
+
+### `A` Parameter
+
+|                |                           |
+| -------------- | ------------------------- |
+| Name:          | A                         |
+| Position:      | *None (Switch Parameter)* |
+| Required:      | *No (Switch Parameter)*   |
+| Default value: | `false`                   |
+
+___
+
+*Documentation generated by [MdDocs](https://github.com/ap0llo/mddocs)*
diff --git a/...t/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt b/...t/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt
@@ -13,8 +13,8 @@
 ## Usage
 
 ```txt
-TestApp CommandName [--xyz <VALUE>]
-                    [-a <VALUE>]
+TestApp CommandName [-a <VALUE>]
+                    [--xyz <VALUE>]
 ```
 
 ## Parameters

diff --git a/...t/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt b/...t/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt
@@ -12,8 +12,8 @@
 ## Usage
 
 ```txt
-TestApp CommandName [--xyz <VALUE>]
-                    [-a <VALUE>]
+TestApp CommandName [-a <VALUE>]
+                    [--xyz <VALUE>]
 ```
 
 ## Parameters

diff --git a/...renceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt b/...renceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt
@@ -0,0 +1,129 @@
+<!--  
+  <auto-generated>   
+    The contents of this file were generated by a tool.  
+    Changes to this file may be list if the file is regenerated  
+  </auto-generated>   
+-->
+
+# TestApp Command Line Reference
+
+**Version:** 1.2.3
+
+## Usage
+
+Usage line 1  
+Usage line2
+
+## Usage
+
+```txt
+TestApp [<VALUE>]
+        [<VALUE>]
+        --paramC <VALUE>
+        --paramD <VALUE>
+        [--paramA <VALUE>]
+        [--paramB <VALUE>]
+        [-A]
+        [--B]
+```
+
+## Parameters
+
+| Position                   | Name                        | Short Name        | Required | Description |
+| -------------------------- | --------------------------- | ----------------- | -------- | ----------- |
+| [1](#parameter-position-1) |                             |                   | No       |             |
+| [2](#parameter-position-2) |                             |                   | No       |             |
+|                            | [paramA](#parama-parameter) |                   | No       |             |
+|                            | [paramB](#paramb-parameter) |                   | No       |             |
+|                            | [paramC](#paramc-parameter) |                   | Yes      |             |
+|                            | [paramD](#paramd-parameter) |                   | Yes      |             |
+|                            | [B](#b-parameter)           |                   | No       |             |
+|                            |                             | [A](#a-parameter) | No       |             |
+
+### Parameter (Position 1)
+
+|                |        |
+| -------------- | ------ |
+| Position:      | 1      |
+| Required:      | No     |
+| Default value: | *None* |
+
+___
+
+### Parameter (Position 2)
+
+|                |        |
+| -------------- | ------ |
+| Position:      | 2      |
+| Required:      | No     |
+| Default value: | *None* |
+
+___
+
+### `paramA` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramA            |
+| Position:      | *Named parameter* |
+| Required:      | No                |
+| Default value: | *None*            |
+
+___
+
+### `paramB` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramB            |
+| Position:      | *Named parameter* |
+| Required:      | No                |
+| Default value: | *None*            |
+
+___
+
+### `paramC` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramC            |
+| Position:      | *Named parameter* |
+| Required:      | Yes               |
+| Default value: | *None*            |
+
+___
+
+### `paramD` Parameter
+
+|                |                   |
+| -------------- | ----------------- |
+| Name:          | paramD            |
+| Position:      | *Named parameter* |
+| Required:      | Yes               |
+| Default value: | *None*            |
+
+___
+
+### `B` Parameter
+
+|                |                           |
+| -------------- | ------------------------- |
+| Name:          | B                         |
+| Position:      | *None (Switch Parameter)* |
+| Required:      | *No (Switch Parameter)*   |
+| Default value: | `false`                   |
+
+___
+
+### `A` Parameter
+
+|                |                           |
+| -------------- | ------------------------- |
+| Name:          | A                         |
+| Position:      | *None (Switch Parameter)* |
+| Required:      | *No (Switch Parameter)*   |
+| Default value: | `false`                   |
+
+___
+
+*Documentation generated by [MdDocs](https://github.com/ap0llo/mddocs)*
diff --git a/src/MdDocs.CommandLineHelp/Templates/Default/_Partials/CommandUsageSection.cs b/src/MdDocs.CommandLineHelp/Templates/Default/_Partials/CommandUsageSection.cs
@@ -36,14 +36,14 @@ protected void AppendParameters(StringBuilder stringBuilder, int indent)
                     .Append(' ', indent);
             }
 
-            foreach (var option in m_Model.NamedParameters)
+            foreach (var option in m_Model.NamedParameters.OrderBy(x => x.Required ? 0 : 1).ThenBy(x => x.HasName ? x.Name : x.ShortName))
             {
                 stringBuilder
                     .Apply(AppendUsage, option)
                     .Append(' ', indent);
             }
 
-            foreach (var option in m_Model.SwitchParameters)
+            foreach (var option in m_Model.SwitchParameters.OrderBy(x => x.HasName ? x.Name : x.ShortName))
             {
                 stringBuilder
                     .Apply(AppendUsage, option)