[build] Rework examples

Author: AndreyAkinshin

build/BenchmarkDotNet.Build/CommandLineParser.cs

@@ -108,78 +108,73 @@ private void PrintHelp()
 
         WriteLine();
 
-        WriteHeader("Examples:");
+        PrintExamples(GetTasks().SelectMany(task => task.HelpInfo.Examples));
 
-        WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask("restore");
-        WriteLine();
+        PrintOptions(baseOptions);
 
-        WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask("build ");
-        WriteOption("/p:");
-        WriteArg("Configuration");
-        WriteOption("=");
-        WriteArg("Debug");
-        WriteLine();
+        WriteHeader("Tasks:");
+        var taskWidth = GetTaskNames().Max(name => name.Length) + 3;
+        foreach (var (taskName, taskDescription, _) in GetTasks())
+        {
+            if (taskName.Equals("Default", StringComparison.OrdinalIgnoreCase))
+                continue;
 
-        WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask("pack ");
-        WriteOption("/p:");
-        WriteArg("VersionPrefix");
-        WriteOption("=");
-        WriteArg("0.1.1729");
-        WriteOption(" /p:");
-        WriteArg("VersionSuffix");
-        WriteOption("=");
-        WriteArg("preview");
-        WriteLine();
+            WriteTask("    " + taskName.PadRight(taskWidth));
+            Write(taskDescription);
 
-        WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask("unit-tests ");
-        WriteOption("--exclusive --verbosity ");
-        WriteArg("Diagnostic");
-        WriteLine();
+            WriteLine();
+        }
+    }
+
+    private void PrintTaskHelp(string taskName)
+    {
+        var taskType = typeof(BuildContext).Assembly
+            .GetTypes()
+            .Where(type => type.IsSubclassOf(typeof(FrostingTask<BuildContext>)) && !type.IsAbstract)
+            .First(type => Is(type.GetCustomAttribute<TaskNameAttribute>()?.Name, taskName));
+        taskName = taskType.GetCustomAttribute<TaskNameAttribute>()!.Name;
+        var taskDescription = taskType.GetCustomAttribute<TaskDescriptionAttribute>()?.Description ?? "";
+        var helpInfo = GetHelpInfo(taskType);
+
+        WriteHeader("Description:");
 
         WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask("docs-update ");
-        WriteOption("--depth ");
-        WriteArg("3");
+        WriteLine(!string.IsNullOrWhiteSpace(taskDescription)
+            ? $"Task '{taskName}': {taskDescription}"
+            : $"Task '{taskName}'");
+
+        if (string.IsNullOrWhiteSpace(helpInfo.Description))
+            foreach (var line in helpInfo.Description.Split('\n', StringSplitOptions.RemoveEmptyEntries))
+            {
+                WritePrefix();
+                WriteLine(line.Trim());
+            }
+
         WriteLine();
 
+        WriteHeader("Usage:");
+
         WritePrefix();
         Write(CallScriptName + " ");
-        WriteTask("docs-build ");
-        WriteOption("--preview ");
+        WriteTask(taskName + " ");
+        WriteOption("[OPTIONS]");
         WriteLine();
 
         WriteLine();
 
-        PrintOptions(baseOptions);
+        PrintExamples(helpInfo.Examples);
 
-        WriteHeader("Tasks:");
-        var taskWidth = GetTaskNames().Max(name => name.Length) + 3;
-        foreach (var (taskName, taskDescription) in GetTasks())
-        {
-            if (taskName.Equals("Default", StringComparison.OrdinalIgnoreCase))
-                continue;
+        PrintOptions(helpInfo.Options.Concat(baseOptions).ToArray());
 
-            if (taskDescription.StartsWith("OBSOLETE", StringComparison.OrdinalIgnoreCase))
-            {
-                WriteObsolete("    " + taskName.PadRight(taskWidth));
-                WriteObsolete(taskDescription);
-            }
-            else
+        if (helpInfo.EnvironmentVariables.Any())
+        {
+            WriteHeader("Environment variables:");
+            foreach (var variable in helpInfo.EnvironmentVariables)
             {
-                WriteTask("    " + taskName.PadRight(taskWidth));
-                Write(taskDescription);
+                WritePrefix();
+                WriteOption(variable);
+                WriteLine();
             }
-
-            WriteLine();
         }
     }
 
@@ -242,88 +237,64 @@ int GetWidth(IOption option)
         WriteLine();
     }
 
-    private void PrintTaskHelp(string taskName)
+    private void PrintExamples(IEnumerable<Example> examples)
     {
-        var taskType = typeof(BuildContext).Assembly
-            .GetTypes()
-            .Where(type => type.IsSubclassOf(typeof(FrostingTask<BuildContext>)) && !type.IsAbstract)
-            .First(type => Is(type.GetCustomAttribute<TaskNameAttribute>()?.Name, taskName));
-        taskName = taskType.GetCustomAttribute<TaskNameAttribute>()!.Name;
-        var taskDescription = taskType.GetCustomAttribute<TaskDescriptionAttribute>()?.Description ?? "";
-        var taskInstance = Activator.CreateInstance(taskType);
-        var helpInfo = taskInstance is IHelpProvider helpProvider ? helpProvider.GetHelp() : new HelpInfo();
-
-        WriteHeader("Description:");
-
-        WritePrefix();
-        WriteLine($"Task '{taskName}'");
-        if (!string.IsNullOrWhiteSpace(taskDescription))
-        {
-            WritePrefix();
-            WriteLine(taskDescription);
-        }
-
-        if (string.IsNullOrWhiteSpace(helpInfo.Description))
-            foreach (var line in helpInfo.Description.Split('\n', StringSplitOptions.RemoveEmptyEntries))
-            {
-                WritePrefix();
-                WriteLine(line.Trim());
-            }
-
-        WriteLine();
-
-        WriteHeader("Usage:");
-
-        WritePrefix();
-        Write(CallScriptName + " ");
-        WriteTask(taskName + " ");
-        WriteOption("[OPTIONS]");
-        WriteLine();
-
-        WriteLine();
-
         WriteHeader("Examples:");
 
-        WritePrefix();
-        Write(ScriptName + " ");
-        WriteTask(taskName);
-        WriteLine();
-
-        WriteLine();
-
-        PrintOptions(helpInfo.Options.Concat(baseOptions).ToArray());
-
-        if (helpInfo.EnvironmentVariables.Any())
+        foreach (var example in examples)
         {
-            WriteHeader("Environment variables:");
-            foreach (var variable in helpInfo.EnvironmentVariables)
+            WritePrefix();
+            Write(CallScriptName + " ");
+            WriteTask(example.TaskName + " ");
+            foreach (var (name, value, isMsBuild) in example.Arguments)
             {
-                WritePrefix();
-                WriteOption(variable);
+                if (isMsBuild)
+                {
+                    WriteOption("/p:");
+                    WriteArg(name);
+                    WriteOption("=");
+                    WriteArg(value + " ");
+                }
+                else
+                {
+                    WriteOption(name + " ");
+                    if (value != null)
+                        WriteArg(value + " ");
+                }
             }
 
             WriteLine();
         }
+
+        WriteLine();
     }
 
     private static HashSet<string> GetTaskNames()
     {
         return GetTasks().Select(task => task.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
     }
 
-    private static List<(string Name, string Description)> GetTasks()
+    private static List<(string Name, string Description, HelpInfo HelpInfo)> GetTasks()
     {
         return typeof(BuildContext).Assembly
             .GetTypes()
             .Where(type => type.IsSubclassOf(typeof(FrostingTask<BuildContext>)) && !type.IsAbstract)
             .Select(type => (
                 Name: type.GetCustomAttribute<TaskNameAttribute>()?.Name ?? "",
-                Description: type.GetCustomAttribute<TaskDescriptionAttribute>()?.Description ?? ""
+                Description: type.GetCustomAttribute<TaskDescriptionAttribute>()?.Description ?? "",
+                HelpInfo: GetHelpInfo(type)
             ))
             .Where(task => task.Name != "")
             .ToList();
     }
 
+    private static HelpInfo GetHelpInfo(Type taskType)
+    {
+        return Activator.CreateInstance(taskType) is IHelpProvider helpProvider
+            ? helpProvider.GetHelp()
+            : new HelpInfo();
+    }
+
     private static bool Is(string? arg, params string[] values) =>
         values.Any(value => value.Equals(arg, StringComparison.OrdinalIgnoreCase));
 

build/BenchmarkDotNet.Build/Example.cs

@@ -0,0 +1,38 @@
+using System.Collections.Generic;
+using BenchmarkDotNet.Build.Options;
+
+namespace BenchmarkDotNet.Build;
+
+public class Example
+{
+    private readonly List<Argument> arguments = new();
+
+    public string TaskName { get; }
+    public IReadOnlyCollection<Argument> Arguments => arguments;
+
+    public Example(string taskName)
+    {
+        TaskName = taskName;
+    }
+
+    public Example WithArgument(string name, string? value = null)
+    {
+        arguments.Add(new Argument(name, value, false));
+        return this;
+    }
+
+    public Example WithMsBuildArgument(string name, string value)
+    {
+        arguments.Add(new Argument(name, value, true));
+        return this;
+    }
+
+    public Example WithArgument(IOption option, string? value = null)
+    {
+        arguments.Add(new Argument(option.CommandLineName, value, false));
+        return this;
+    }
+
+
+    public record Argument(string Name, string? Value, bool IsMsBuild);
+}

build/BenchmarkDotNet.Build/HelpInfo.cs

@@ -8,4 +8,5 @@ public class HelpInfo
     public string Description { get; init; } = "";
     public IOption[] Options { get; init; } = Array.Empty<IOption>();
     public string[] EnvironmentVariables { get; init; } = Array.Empty<string>();
+    public Example[] Examples { get; init; } = Array.Empty<Example>();
 }