Improve XmlDoc output (#1503)

* Add command description and examples in XML Output Closes #1115
spectreconsole · Mar 29, 2024 · 1a3249c · 1a3249c
1 parent 43f9ae9
commit 1a3249c
Show file tree

Hide file tree

Showing 11 changed files with 87 additions and 0 deletions.
diff --git a/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs b/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
@@ -84,6 +84,13 @@ private static XmlNode CreateCommandNode(XmlDocument doc, CommandInfo command, b
 
         node.SetNullableAttribute("Settings", command.SettingsType?.FullName);
 
+        if (!string.IsNullOrWhiteSpace(command.Description))
+        {
+            var descriptionNode = doc.CreateElement("Description");
+            descriptionNode.InnerText = command.Description;
+            node.AppendChild(descriptionNode);
+        }
+
         // Parameters
         if (command.Parameters.Count > 0)
         {
@@ -103,6 +110,27 @@ private static XmlNode CreateCommandNode(XmlDocument doc, CommandInfo command, b
             node.AppendChild(CreateCommandNode(doc, childCommand));
         }
 
+        // Examples
+        if (command.Examples.Count > 0)
+        {
+            var exampleRootNode = doc.CreateElement("Examples");
+            foreach (var example in command.Examples.SelectMany(static x => x))
+            {
+                var exampleNode = CreateExampleNode(doc, example);
+                exampleRootNode.AppendChild(exampleNode);
+            }
+
+            node.AppendChild(exampleRootNode);
+        }
+
+        return node;
+    }
+
+    private static XmlNode CreateExampleNode(XmlDocument document, string example)
+    {
+        var node = document.CreateElement("Example");
+        node.SetAttribute("commandLine", example);
+
         return node;
     }
 

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt
@@ -21,13 +21,15 @@
       </Parameters>
       <!--DOG-->
       <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+        <Description>The dog command.</Description>
         <Parameters>
           <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
           <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
         </Parameters>
       </Command>
       <!--HORSE-->
       <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+        <Description>The horse command.</Description>
         <Parameters>
           <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
           <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Model>
+  <!--DOG-->
+  <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
+    <Parameters>
+      <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
+        <Description>The number of legs.</Description>
+        <Validators>
+          <Validator ClrType="Spectre.Console.Tests.Data.EvenNumberValidatorAttribute" Message="Animals must have an even number of legs." />
+          <Validator ClrType="Spectre.Console.Tests.Data.PositiveNumberValidatorAttribute" Message="Number of legs must be greater than 0." />
+        </Validators>
+      </Argument>
+      <Argument Name="AGE" Position="1" Required="true" Kind="scalar" ClrType="System.Int32" />
+      <Option Short="a" Long="alive,not-dead" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean">
+        <Description>Indicates whether or not the animal is alive.</Description>
+      </Option>
+      <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
+      <Option Short="n,p" Long="name,pet-name" Value="VALUE" Required="false" Kind="scalar" ClrType="System.String" />
+    </Parameters>
+    <Examples>
+      <Example commandLine="dog -g" />
+      <Example commandLine="dog --good-boy" />
+    </Examples>
+  </Command>
+</Model>
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt
@@ -2,6 +2,7 @@
 <Model>
   <!--DOG-->
   <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -24,6 +25,7 @@
     </Command>
     <!--HORSE-->
     <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt
@@ -2,6 +2,7 @@
 <Model>
   <!--DEFAULT COMMAND-->
   <Command Name="__default_command" IsBranch="false" IsDefault="true" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>
@@ -20,6 +21,7 @@
   </Command>
   <!--HORSE-->
   <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+    <Description>The horse command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt
@@ -21,6 +21,7 @@
       </Parameters>
       <!--__DEFAULT_COMMAND-->
       <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+        <Description>The horse command.</Description>
         <Parameters>
           <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
           <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -24,6 +25,7 @@
     </Command>
     <!--__DEFAULT_COMMAND-->
     <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt
@@ -18,6 +18,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -26,6 +27,7 @@
     </Command>
     <!--__DEFAULT_COMMAND-->
     <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

diff --git a/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs b/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs
@@ -110,6 +110,26 @@ public Task Should_Dump_Correct_Model_For_Case_5()
             return Verifier.Verify(result.Output);
         }
 
+        [Fact]
+        [Expectation("Test_10")]
+        public Task Should_Dump_Correct_Model_For_Case_6()
+        {
+            // Given
+            var fixture = new CommandAppTester();
+            fixture.Configure(config =>
+            {
+                config.AddCommand<DogCommand>("dog")
+                    .WithExample("dog -g")
+                    .WithExample("dog --good-boy");
+            });
+
+            // When
+            var result = fixture.Run(Constants.XmlDocCommand);
+
+            // Then
+            return Verifier.Verify(result.Output);
+        }
+
         [Fact]
         [Expectation("Test_6")]
         public Task Should_Dump_Correct_Model_For_Model_With_Default_Command()