From e51f605be1cf0641ee7ba48f244e6c87f9d67150 Mon Sep 17 00:00:00 2001 From: Andreas Gruenwald Date: Sat, 20 Feb 2021 11:02:59 +0100 Subject: [PATCH] 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) --- .../commandline/commands/Command1.md | 2 +- .../Default/_Documents/CommandPageTest.cs | 22 +++ .../SingleCommandApplicationPageTest.cs | 27 ++++ ...ommand_parameters_are_ordered.approved.txt | 125 +++++++++++++++++ ..._returns_expected_document_11.approved.txt | 4 +- ..._returns_expected_document_12.approved.txt | 4 +- ...ommand_parameters_are_ordered.approved.txt | 129 ++++++++++++++++++ .../Default/_Partials/CommandUsageSection.cs | 4 +- 8 files changed, 310 insertions(+), 7 deletions(-) create mode 100644 src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt create mode 100644 src/MdDocs.CommandLineHelp.Test/_referenceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt diff --git a/docs/demoprojects/commandline/commands/Command1.md b/docs/demoprojects/commandline/commands/Command1.md index e5554f26..ae8f1c7e 100644 --- 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 [] [] + --parameter4 [--parameter1 ] [--parameter2|-x ] - --parameter4 [--parameter5 ] [-y ] ``` diff --git a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs index c2582e0c..76fd4bc2 100644 --- 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/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs index 42950c1d..8f822a25 100644 --- a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs +++ b/src/MdDocs.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/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt new file mode 100644 index 00000000..304ceebf --- /dev/null +++ b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.Command_parameters_are_ordered.approved.txt @@ -0,0 +1,125 @@ + + +# `CommandName` Command + +**Application:** [TestApp](../index.md) +**Version:** 1.2.3 + +## Usage + +```txt +TestApp CommandName [] + [] + --paramC + --paramD + [--paramA ] + [--paramB ] + [-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.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt index a34d43fa..32dd2361 100644 --- a/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt +++ b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_11.approved.txt @@ -13,8 +13,8 @@ ## Usage ```txt -TestApp CommandName [--xyz ] - [-a ] +TestApp CommandName [-a ] + [--xyz ] ``` ## Parameters diff --git a/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt index 45bbb1c3..8a48cf77 100644 --- a/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt +++ b/src/MdDocs.CommandLineHelp.Test/_referenceResults/CommandPageTest.GetDocument_returns_expected_document_12.approved.txt @@ -12,8 +12,8 @@ ## Usage ```txt -TestApp CommandName [--xyz ] - [-a ] +TestApp CommandName [-a ] + [--xyz ] ``` ## Parameters diff --git a/src/MdDocs.CommandLineHelp.Test/_referenceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt b/src/MdDocs.CommandLineHelp.Test/_referenceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt new file mode 100644 index 00000000..ef9712ed --- /dev/null +++ b/src/MdDocs.CommandLineHelp.Test/_referenceResults/SingleCommandApplicationPageTest.Command_parameters_are_ordered.approved.txt @@ -0,0 +1,129 @@ + + +# TestApp Command Line Reference + +**Version:** 1.2.3 + +## Usage + +Usage line 1 +Usage line2 + +## Usage + +```txt +TestApp [] + [] + --paramC + --paramD + [--paramA ] + [--paramB ] + [-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 index bdcabe7a..b449dd11 100644 --- 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)