Add comments

Author: NikolayPianikov

CSharpInteractive.HostApi/DotNetCommands.cs

@@ -1,7 +1,7 @@
 <#@ import namespace="System.Linq" #>
-<#@ import namespace="System.Linq" #>
-<#@ import namespace="System.Linq" #>
 <#@ import namespace="System.Collections.Generic" #>
+<#@ import namespace="System.IO" #>
+<#@ import namespace="System.Xml" #>
 // ReSharper disable UnusedMember.Global
 // ReSharper disable InconsistentNaming
 namespace HostApi;
@@ -17,7 +17,7 @@ using Internal;
 
     string CreateCliRef(string command) => 
         $"<br/><a href=\"https://learn.microsoft.com/en-us/dotnet/core/tools/{command}\">.NET CLI command</a><br/>";
-
+    
     var projectArg = new Arg("Project", "", "string", "The project or solution file to operate on. If not specified, the command searches the current directory for one. If more than one solution or project is found, an error is thrown.") { IsProject = true };
     var solutionArg = new Arg("Solution", "", "string", "The solution file to use. If this argument is omitted, the command searches the current directory for one. If it finds no solution file or multiple solution files, the command fails.") { IsProject = true };
     var propsArg = new Arg("Props", "--property", "IEnumerable<(string name, string value)>", "MSBuild options for setting properties.") { IsCollection = true };
@@ -116,11 +116,11 @@ using Internal;
                 paraFinish,
                 CreateCliRef("dotnet-add-package")
             ],
-            ["add", "$Project", "package", "$PackageName"],
+            ["add", "$Project", "package", "$Package"],
             [
                 sourcesArg,
                 projectArg,
-                new Arg("PackageName", "", "string", "The package reference to add."),
+                new Arg("Package", "", "string", "The package reference to add."),
                 frameworkArg with { Comments = "Adds a package reference only when targeting a specific framework." },
                 noRestoreArg,
                 new Arg("PackageDirectory", "--package-directory", "string", @"The directory where to restore the packages. The default package restore location is %userprofile%\.nuget\packages on Windows and ~/.nuget/packages on macOS and Linux."),
@@ -163,10 +163,10 @@ using Internal;
                 paraFinish,
                 CreateCliRef("dotnet-remove-package")
             ],
-            ["remove", "$Project", "package", "$PackageName"],
+            ["remove", "$Project", "package", "$Package"],
             [
                 projectArg,
-                new Arg("PackageName", "", "string", "The package reference to add."),
+                new Arg("Package", "", "string", "The package reference to add."),
                 diagnosticsArg
             ]
         ),
@@ -181,7 +181,7 @@ using Internal;
             ],
             ["add", "$Project", "reference", "$References"],
             [
-                new Arg("References", "--source", "IEnumerable<string>", "Project-to-project (P2P) references to add. Specify one or more projects. Glob patterns are supported on Unix/Linux-based systems.") { IsCollection = true },
+                new Arg("References", "", "IEnumerable<string>", "Project-to-project (P2P) references to add. Specify one or more projects. Glob patterns are supported on Unix/Linux-based systems.") { IsProject = true, IsCollection = true },
                 projectArg,
                 frameworkArg with { Comments = "Adds project references only when targeting a specific framework using the TFM format." },
                 diagnosticsArg
@@ -196,7 +196,7 @@ using Internal;
                 paraFinish,
                 CreateCliRef("dotnet-list-reference")
             ],
-            ["list", "$Project"],
+            ["list", "$Project", "reference"],
             [
                 projectArg,
                 diagnosticsArg
@@ -213,7 +213,7 @@ using Internal;
             ],
             ["remove", "$Project", "reference", "$References"],
             [
-                new Arg("References", "--source", "IEnumerable<string>", "Project-to-project (P2P) references to remove. You can specify one or multiple projects. Glob patterns are supported on Unix/Linux based terminals.") { IsCollection = true },
+                new Arg("References", "", "IEnumerable<string>", "Project-to-project (P2P) references to remove. You can specify one or multiple projects. Glob patterns are supported on Unix/Linux based terminals.") { IsProject = true, IsCollection = true },
                 projectArg,
                 frameworkArg with { Comments = "Removes the reference only when targeting a specific framework using the TFM format." },
                 diagnosticsArg
@@ -229,15 +229,6 @@ using Internal;
                 paraStart,
                 "For executable projects targeting .NET Core 3.0 and later, library dependencies are copied to the output folder. This means that if there isn't any other publish-specific logic (such as Web projects have), the build output should be deployable.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "var configuration = Props.Get(\"configuration\", \"Release\");",
-                "",
-                "",
-                "new DotNetBuild().WithConfiguration(configuration)",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-build")
             ],
             ["build", "$Project"],
@@ -344,15 +335,6 @@ using Internal;
                 paraStart,
                 "This command creates a .NET project or other artifacts based on a template. The command calls the template engine to create the artifacts on disk based on the specified template and options.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetNew()",
-                "    .WithTemplateName(\"console\")",
-                "    .WithName(\"MyApp\")",
-                "    .WithForce(true)",
-                "    .Run().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-new")
             ],
             ["new", "$TemplateName"],
@@ -498,9 +480,9 @@ using Internal;
                 paraFinish,
                 CreateCliRef("dotnet-nuget-delete")
             ],
-            ["nuget", "delete", "$PackageName", "$PackageVersion"],
+            ["nuget", "delete", "$Package", "$PackageVersion"],
             [
-                new Arg("PackageName", "", "string", "Name/ID of the package to delete.") { IsProject = true },
+                new Arg("Package", "", "string", "Name/ID of the package to delete.") { IsProject = true },
                 new Arg("PackageVersion", "", "string", "Version of the package to delete.") { IsProject = true },
                 new Arg("ForceEnglishOutput", "--force-english-output", "bool?", "Forces the application to run using an invariant, English-based culture."),
                 new Arg("ApiKey", "--api-key", "string", "The API key for the server."),
@@ -931,12 +913,6 @@ using Internal;
                 paraStart,
                 "By default, dotnet pack builds the project first. If you wish to avoid this behavior, pass the --no-build option. This option is often useful in Continuous Integration (CI) build scenarios where you know the code was previously built.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetPack()",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-pack")
             ],
             ["pack", "$Project"],
@@ -997,12 +973,6 @@ using Internal;
                 paraStart,
                 "This command compiles the application, reads through its dependencies specified in the project file, and publishes the resulting set of files to a directory.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetPublish().AddProps((\"PublishDir\", \".publish\"))",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-publish")
             ],
             ["publish", "$Project"],
@@ -1044,12 +1014,6 @@ using Internal;
                 paraStart,
                 "Sometimes, it might be inconvenient to run the implicit NuGet restore with these commands. For example, some automated systems, such as build systems, need to call dotnet restore explicitly to control when the restore occurs so that they can control network usage. To prevent the implicit NuGet restore, you can use the --no-restore flag with any of these commands.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetRestore()",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-restore")
             ],
             ["restore", "$Project"],
@@ -1088,19 +1052,6 @@ using Internal;
                 paraStart,
                 "To run the application, the dotnet run command resolves the dependencies of the application that are outside of the shared runtime from the NuGet cache. Because it uses cached dependencies, it's not recommended to use dotnet run to run applications in production. Instead, create a deployment using the dotnet publish command and deploy the published output.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetNew()",
-                "    .WithTemplateName(\"console\")",
-                "    .WithName(\"MyApp\")",
-                "    .WithForce(true)",
-                "    .Run().EnsureSuccess();",
-                "",
-                "",
-                "new DotNetRun().WithWorkingDirectory(\"MyApp\")",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-run")
             ],
             ["run"],
@@ -1210,19 +1161,6 @@ using Internal;
                 paraStart,
                 "For multi-targeted projects, tests are run for each targeted framework. The test host and the unit test framework are packaged as NuGet packages and are restored as ordinary dependencies for the project. Starting with the .NET 9 SDK, these tests are run in parallel by default. To disable parallel execution, set the TestTfmsInParallel MSBuild property to false.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetNew()",
-                "    .WithTemplateName(\"mstest\")",
-                "    .WithName(\"MyTests\")",
-                "    .WithForce(true)",
-                "    .Run().EnsureSuccess();",
-                "",
-                "",
-                "new DotNetTest().WithWorkingDirectory(\"MyTests\")",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-test")
             ],
             ["test", "$Project"],
@@ -1636,6 +1574,33 @@ using Internal;
 /// <#= comment #>
 <#
         }
+
+        var exampleFile = Path.Combine("..", "CSharpInteractive.Tests", "UsageScenarios", "Comments", $"{command.Name}Scenario.txt");
+        if (File.Exists(exampleFile))
+        {
+            var exampleLines = File.ReadAllLines(exampleFile);
+            if (exampleLines.Length > 0)
+            {
+#>
+/// <#= exampleStart #>
+///<#= codeStart #>
+<#
+                var doc = new XmlDocument();
+                foreach (var exampleLine in exampleLines.Select(i => i.TrimEnd()))
+                {
+                    var node = doc.CreateElement("root");
+                    node.InnerText = exampleLine;
+                    var line = node.InnerXml;
+#>
+/// <#= line #>
+<#
+                }
+#>
+///<#= codeFinish #>
+/// <#= exampleFinish #>
+<#
+            }
+        }
 #>
 /// </summary>
 /// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
@@ -1743,8 +1708,12 @@ public partial record <#= command.Name #>(
                 {
                     notEmptyArg = $"{notEmptyArg}.ToArray()";
                 }
+                else
+                {
+                    notEmptyArg = $"{notEmptyArg}.ToArg()";
+                }
 #>
-            .AddNotEmptyArgs(<#= notEmptyArg #>.ToArg())
+            .AddNotEmptyArgs(<#= notEmptyArg #>)
 <#
             }
             else

CSharpInteractive.HostApi/DotNetCommands.tt

@@ -161,6 +161,11 @@ public static string[] ToArgs(this IEnumerable<string> values, string name, stri
         }
 
         var str = string.Join(collectionSeparator, values);
+        if (string.IsNullOrWhiteSpace(str))
+        {
+            return [];
+        }
+
         return string.IsNullOrWhiteSpace(str) ? [] : [name, str];
     }