Adds xml docs

CSharpInteractive.HostApi/BuildMessage.cs

@@ -5,30 +5,67 @@ namespace HostApi;
 
 using JetBrains.TeamCity.ServiceMessages;
 
+/// <summary>
+/// Represents a build event.
+/// </summary>
+/// <param name="Output">Event from the running command line.</param>
+/// <param name="State">State of the build message. Defines the specifics of the build message, what information it contains.</param>
+/// <param name="ServiceMessage">Associated service message.</param>
+/// <param name="Text">Text of the build message.</param>
+/// <param name="ErrorDetails">Details of the build message error.</param>
+/// <param name="Code">Message code of the build message.</param>
+/// <param name="File">A file that is relevant to the build event.</param>
+/// <param name="Subcategory">Message subcategory of the build message.</param>
+/// <param name="ProjectFile">A project that is relevant to the build event.</param>
+/// <param name="SenderName">The task that initiated the build message.</param>
+/// <param name="ColumnNumber">Start position in a line of the file relevant to the build event.</param>
+/// <param name="EndColumnNumber">End position in a line of the file relevant to the build event.</param>
+/// <param name="LineNumber">First line of the file relating to the build event.</param>
+/// <param name="EndLineNumber">Last line of the file relating to the build event.</param>
+/// <param name="Importance">Importance of the build event.</param>
 [ExcludeFromCodeCoverage]
 [Target]
 public record BuildMessage(
+    // Event from the running command line.
     Output Output,
+    // State of the build message. Defines the specifics of the build message, what information it contains.
     BuildMessageState State,
+    // Associated service message.
     IServiceMessage? ServiceMessage = default,
+    // Text of the build message.
     string Text = "",
+    // Details of the build message error.
     string ErrorDetails = "",
+    // Message code of the build message.
     string Code = "",
+    // A file that is relevant to the build event.
     string File = "",
+    // Message subcategory of the build message.
     string Subcategory = "",
+    // A project that is relevant to the build event.
     string ProjectFile = "",
+    // The task that initiated the build message.
     string SenderName = "",
+    // Start position in a line of the file relevant to the build event.
     int? ColumnNumber = default,
+    // End position in a line of the file relevant to the build event.
     int? EndColumnNumber = default,
+    // First line of the file relating to the build event.
     int? LineNumber = default,
+    // Last line of the file relating to the build event.
     int? EndLineNumber = default,
+    // Importance of the build event.
     DotNetMessageImportance? Importance = default)
 {
+    /// <summary>
+    /// Contains the result of test execution when <see cref="State"/> is set to <see cref="BuildMessageState.TestResult"/>.
+    /// </summary>
     public TestResult? TestResult => 
-        ServiceMessage is { } message && TryGetTestState(message.Name, out var testState)
-            ? CreateResult(CreateKey(message), message, testState)
+        ServiceMessage != null && TryGetTestState(ServiceMessage.Name, out var testState)
+            ? CreateResult(CreateKey(ServiceMessage), ServiceMessage, testState)
             : default(TestResult?);
 
+    /// <inheritdoc />
     public override string ToString() => Text;
 
     internal static TestResult CreateResult(TestKey key, IServiceMessage message, TestState state)

CSharpInteractive.HostApi/BuildMessageState.cs

@@ -2,13 +2,43 @@
 // ReSharper disable UnusedMember.Global
 namespace HostApi;
 
+/// <summary>
+/// State of a build message. Defines the specifics of the build message, what information it contains.
+/// </summary>
 public enum BuildMessageState
 {
+    /// <summary>
+    /// Service message of a build. 
+    /// </summary>
     ServiceMessage,
+
+    /// <summary>
+    /// The message that the string was sent to stdOut. 
+    /// </summary>
     StdOut,
+
+    /// <summary>
+    /// Build warning.
+    /// </summary>
     Warning,
+
+    /// <summary>
+    /// The message that the string was sent to stdErr.
+    /// </summary>
     StdError,
+
+    /// <summary>
+    /// Build error.
+    /// </summary>
     Failure,
+
+    /// <summary>
+    /// Build problem.
+    /// </summary>
     BuildProblem,
+
+    /// <summary>
+    /// Indicates that the message contains information about test execution.
+    /// </summary>
     TestResult
 }

CSharpInteractive.HostApi/BuildStatistics.cs

@@ -2,16 +2,34 @@ namespace HostApi;
 
 using System.Text;
 
+/// <summary>
+/// Summary of a build.
+/// </summary>
+/// <param name="Errors">Number of build errors.</param>
+/// <param name="Warnings">Number of build warnings.</param>
+/// <param name="Tests">Number of tests.</param>
+/// <param name="FailedTests">Number of failed tests.</param>
+/// <param name="IgnoredTests">Number of ignored tests.</param>
+/// <param name="PassedTests">Number of successful tests.</param>
 [ExcludeFromCodeCoverage]
 [Target]
 public record BuildStatistics(
+    // Number of build errors.
     int Errors = default,
+    // Number of build warnings.
     int Warnings = default,
+    // Number of tests.
     int Tests = default,
+    // Number of failed tests.
     int FailedTests = default,
+    // Number of ignored tests.
     int IgnoredTests = default,
+    // Number of successful tests.
     int PassedTests = default)
 {
+    /// <summary>
+    /// <c>True></c> if the statistic is empty, <c>False</c> if it contains any information.
+    /// </summary>
     public bool IsEmpty =>
         Errors == 0
         && Warnings == 0
@@ -20,6 +38,7 @@ public record BuildStatistics(
         && IgnoredTests == 0
         && PassedTests == 0;
 
+    /// <inheritdoc />
     public override string ToString()
     {
         if (IsEmpty)

CSharpInteractive.HostApi/CSharpInteractive.HostApi.csproj

@@ -7,10 +7,12 @@
         <IsPackable>false</IsPackable>
         <RootNamespace>HostApi</RootNamespace>
         <ImmutypeAPI>True</ImmutypeAPI>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>CS1591</NoWarn>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Immutype" Version="1.0.14">
+        <PackageReference Include="Immutype" Version="1.0.15">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
         </PackageReference>

CSharpInteractive.HostApi/Color.cs

@@ -1,13 +1,53 @@
 namespace HostApi;
 
+/// <summary>
+/// Logical colors.
+/// <example>
+/// <code>
+/// WriteLine("Hello !!!", Color.Highlighted);
+/// </code>
+/// </example>
+/// </summary>
+/// <seealso cref="IHost.WriteLine"/>
 public enum Color
 {
+    /// <summary>
+    /// Standard text output color.
+    /// </summary>
     Default,
+
+    /// <summary>
+    /// The color of the header output. 
+    /// </summary>
     Header,
+
+    /// <summary>
+    /// Color of trace messages. 
+    /// </summary>
     Trace,
+
+    /// <summary>
+    /// Color of the success messages. 
+    /// </summary>
     Success,
+
+    /// <summary>
+    /// Color of messages containing warnings.
+    /// </summary>
     Warning,
+
+    /// <summary>
+    /// Color of messages containing errors.
+    /// </summary>
     Error,
+
+    /// <summary>
+    /// Colour for details.
+    /// </summary>
     Details,
+
+    /// <summary>
+    /// Colour to display important information.
+    /// </summary>
     Highlighted
 }

CSharpInteractive.HostApi/CommandLine.cs

@@ -8,7 +8,17 @@ namespace HostApi;
 
 /// <summary>
 /// Runs an arbitrary executable with arguments and environment variables from the working directory.
+/// <example>
+/// <code>
+/// var cmd = new CommandLine("whoami");
+/// cmd.Run().EnsureSuccess();
+/// </code>
+/// </example>
 /// </summary>
+/// <seealso cref="ICommandLineRunner.Run"/>
+/// <seealso cref="ICommandLineRunner.RunAsync"/>
+/// <seealso cref="IBuildRunner.Build"/>
+/// <seealso cref="IBuildRunner.BuildAsync"/>
 [Target]
 [DebuggerTypeProxy(typeof(CommandLineDebugView))]
 public partial record CommandLine(
@@ -26,6 +36,11 @@ public partial record CommandLine(
 {
     private readonly string _shortName = ShortName;
 
+    /// <summary>
+    /// Creates a new command line.
+    /// </summary>
+    /// <param name="executablePath">Path to the executable file.</param>
+    /// <param name="args">Command line arguments.</param>
     public CommandLine(string executablePath, params string[] args)
         : this(executablePath, string.Empty, args, Array.Empty<(string name, string value)>())
     { }
@@ -34,14 +49,20 @@ internal CommandLine(IStartInfo startInfo)
         : this(startInfo.ExecutablePath, startInfo.WorkingDirectory, startInfo.Args, startInfo.Vars, startInfo.ShortName)
     { }
 
-    public string ShortName => !string.IsNullOrWhiteSpace(_shortName) ? _shortName : Path.GetFileNameWithoutExtension(ExecutablePath);
+    /// <inheritdoc/>
+    public string ShortName => 
+        !string.IsNullOrWhiteSpace(_shortName)
+            ? _shortName
+            : Path.GetFileNameWithoutExtension(ExecutablePath);
 
+    /// <inheritdoc/>
     public IStartInfo GetStartInfo(IHost host)
     {
         if (host == null) throw new ArgumentNullException(nameof(host));
         return this;
     }
 
+    /// <inheritdoc/>
     public override string ToString()
     {
         var sb = new StringBuilder();
@@ -68,7 +89,6 @@ private static string Escape(string text) =>
 
     internal class CommandLineDebugView(IStartInfo startInfo)
     {
-
         public string ShortName => startInfo.ShortName;
 
         public string ExecutablePath => startInfo.ExecutablePath;

CSharpInteractive.HostApi/CommandLineTools.cs

@@ -1,10 +1,46 @@
 namespace HostApi;
 
+/// <summary>
+/// Command line extensions. Facilitate the use of the command line.
+/// </summary>
 [ExcludeFromCodeCoverage]
 public static class CommandLineTools
 {
-    public static CommandLine AsCommandLine(this string executable, params string[] args) => new(executable, args);
+    /// <summary>
+    /// Creates a new command line from the executable file path and arguments.
+    /// <example>
+    /// <code>
+    /// "whoami".AsCommandLine().Run().EnsureSuccess();
+    /// </code>
+    /// </example>
+    /// </summary>
+    /// <param name="executable">Path to the executable file.</param>
+    /// <param name="args">Command line arguments.</param>
+    /// <returns>Created command line.</returns>
+    public static CommandLine AsCommandLine(this string executable, params string[] args) =>
+        new(executable, args);
 
+    /// <summary>
+    /// Customizes a command line by overriding its parameters as command line arguments and others.
+    /// <example>
+    /// <code>
+    /// var test = new DotNetTest().WithFilter("Integration!=true");
+    ///
+    /// 
+    /// test.Customize(cmd =>
+    ///     cmd.WithArgs("dotcover")
+    ///         .AddArgs(cmd.Args)
+    ///         .AddArgs(
+    ///             $"--dcOutput=dotCover.dcvr",
+    ///             "--dcFilters=+:module=MyLib;+:module=MyLib2",
+    ///             "--dcAttributeFilters=System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage"))
+    ///     .Build().EnsureSuccess();
+    /// </code>
+    /// </example>
+    /// </summary>
+    /// <param name="baseCommandLine">The base command for customization.</param>
+    /// <param name="customizer">Customization function.</param>
+    /// <returns>Customized command line.</returns>
     public static ICommandLine Customize(this ICommandLine baseCommandLine, Func<CommandLine, ICommandLine> customizer) => 
         new CustomCommandLine(baseCommandLine, customizer);
 

CSharpInteractive.HostApi/DockerCustom.cs

@@ -7,6 +7,18 @@ namespace HostApi;
 
 /// <summary>
 /// The docker custom command is used to execute any docker commands with any arguments.
+/// <example>
+/// <code>
+/// var hasLinuxDocker = false;
+/// new DockerCustom("info").Run(output =>
+///     {
+///         if (output.Line.Contains("OSType: linux"))
+///         {
+///             hasLinuxDocker = true;
+///         }
+///     });
+/// </code>
+/// </example>
 /// </summary>
 [Target]
 public partial record DockerCustom(
@@ -21,10 +33,15 @@ public partial record DockerCustom(
     // Specifies a short name for this operation.
     string ShortName = "")
 {
+    /// <summary>
+    /// Create a new instance of the command.
+    /// </summary>
+    /// <param name="args">Specifies the set of command line arguments to use when starting the tool.</param>
     public DockerCustom(params string[] args)
         : this(args, [])
     { }
 
+    /// <inheritdoc/>
     public IStartInfo GetStartInfo(IHost host)
     {
         if (host == null) throw new ArgumentNullException(nameof(host));
@@ -35,6 +52,7 @@ public IStartInfo GetStartInfo(IHost host)
             .WithArgs(Args.ToArray());
     }
 
+    /// <inheritdoc/>
     public override string ToString() => 
         string.IsNullOrWhiteSpace(ShortName) 
             ? ((ExecutablePath == string.Empty ? "docker" : Path.GetFileNameWithoutExtension(ExecutablePath)) + " " + Args.FirstOrDefault()).TrimEnd()