Markup PowerShellEditorServices.Hosting

Author: andyleejordan

src/PowerShellEditorServices.Hosting/BuildInfo.cs

@@ -4,6 +4,7 @@ namespace Microsoft.PowerShell.EditorServices.Hosting
 {
     public static class BuildInfo
     {
+        // TODO: Include a Git commit hash in this.
         public static readonly string BuildVersion = "<development-build>";
         public static readonly string BuildOrigin = "<development>";
         public static readonly System.DateTime? BuildTime = System.DateTime.Parse("2019-12-06T21:43:41", CultureInfo.InvariantCulture.DateTimeFormat);

src/PowerShellEditorServices.Hosting/Configuration/HostLogger.cs

@@ -14,9 +14,12 @@ namespace Microsoft.PowerShell.EditorServices.Hosting
 {
     /// <summary>
     /// User-facing log level for editor services configuration.
-    /// The underlying values of this enum align to both Microsoft.Logging.Extensions.LogLevel
-    /// and Serilog.Events.LogEventLevel.
     /// </summary>
+    /// <remarks>
+    /// The underlying values of this enum attempt to align to both <see
+    /// cref="Microsoft.Logging.Extensions.LogLevel"</see> and <see
+    /// cref="Serilog.Events.LogEventLevel"</see>.
+    /// </remarks>
     public enum PsesLogLevel
     {
         Diagnostic = 0,
@@ -27,9 +30,14 @@ public enum PsesLogLevel
     }
 
     /// <summary>
-    /// A logging front-end for host startup allowing handover to the backend
-    /// and decoupling from the host's particular logging sink.
+    /// A logging front-end for host startup allowing handover to the backend and decoupling from
+    /// the host's particular logging sink.
     /// </summary>
+    /// <remarks>
+    /// This custom logger exists to allow us to log during startup, which is vital information for
+    /// debugging, but happens before we can load any logger library. This is because startup
+    /// happens in our isolated assembly environment. See #2292 for more information.
+    /// </remarks>
     public sealed class HostLogger :
         IObservable<(PsesLogLevel logLevel, string message)>,
         IObservable<(int logLevel, string message)>

src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs

@@ -263,11 +263,7 @@ private void UpdatePSModulePath()
 
         private void LogHostInformation()
         {
-            _logger.Log(PsesLogLevel.Diagnostic, "Logging host information");
-
-_logger.Log(PsesLogLevel.Diagnostic, $@"
-PID: {System.Diagnostics.Process.GetCurrentProcess().Id}
-");
+            _logger.Log(PsesLogLevel.Verbose, $"PID: {System.Diagnostics.Process.GetCurrentProcess().Id}");
 
             _logger.Log(PsesLogLevel.Verbose, $@"
 == Build Details ==

src/PowerShellEditorServices.Hosting/Internal/EditorServicesRunner.cs

@@ -1,18 +1,23 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using Microsoft.PowerShell.EditorServices.Server;
 using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Threading.Tasks;
+using Microsoft.PowerShell.EditorServices.Server;
 
 namespace Microsoft.PowerShell.EditorServices.Hosting
 {
     /// <summary>
     /// Class to manage the startup of PowerShell Editor Services.
-    /// This should be called by <see cref="EditorServicesLoader"/> only after Editor Services has been loaded.
     /// </summary>
+    /// <remarks>
+    /// This should be called by <see cref="EditorServicesLoader"/> only after Editor Services has
+    /// been loaded. It relies on <see cref="EditorServicesServerFactory"/> to indirectly load <see
+    /// cref="Microsoft.Extensions.Logging"/> and <see
+    /// cref="Microsoft.Extensions.DependencyInjection"/>.
+    /// </remarks>
     internal class EditorServicesRunner : IDisposable
     {
         private readonly HostLogger _logger;
@@ -36,6 +41,7 @@ public EditorServicesRunner(
             _logger = logger;
             _config = config;
             _sessionFileWriter = sessionFileWriter;
+            // NOTE: This factory helps to isolate `Microsoft.Extensions.Logging/DependencyInjection`.
             _serverFactory = EditorServicesServerFactory.Create(_config.LogPath, (int)_config.LogLevel, logger);
             _alreadySubscribedDebug = false;
             _loggersToUnsubscribe = loggersToUnsubscribe;
@@ -44,10 +50,13 @@ public EditorServicesRunner(
         /// <summary>
         /// Start and run Editor Services and then wait for shutdown.
         /// </summary>
+        /// <remarks>
+        /// TODO: Use "Async" suffix in names of methods that return an awaitable type.
+        /// </remarks>
         /// <returns>A task that ends when Editor Services shuts down.</returns>
         public Task RunUntilShutdown()
         {
-            // Start Editor Services
+            // Start Editor Services (see function below)
             Task runAndAwaitShutdown = CreateEditorServicesAndRunUntilShutdown();
 
             // Now write the session file
@@ -59,14 +68,60 @@ public Task RunUntilShutdown()
             return runAndAwaitShutdown;
         }
 
+        /// <remarks>
+        /// TODO: This class probably should not be <see cref="IDisposable"/> as the primary
+        /// intention of that interface is to provide cleanup of unmanaged resources, which the
+        /// logger certainly is not. Nor is this class used with a <see langword="using"/>. It is
+        /// only because of the use of <see cref="_serverFactory"/> that this class is also
+        /// disposable, and instead that class should be fixed.
+        /// </remarks>
         public void Dispose()
         {
             _serverFactory.Dispose();
         }
 
         /// <summary>
-        /// Master method for instantiating, running and waiting for the LSP and debug servers at the heart of Editor Services.
+        /// This is the servers' entry point, e.g. <c>main</c>, as it instantiates, runs and waits
+        /// for the LSP and debug servers at the heart of Editor Services. Uses <see
+        /// cref="HostStartupInfo"/>.
         /// </summary>
+        /// <remarks>
+        /// The logical stack of the program is:
+        /// <list type="number">
+        /// <listheader>
+        ///     <term>Symbol</term>
+        ///     <description>Description</description>
+        /// </listheader>
+        /// <item>
+        ///     <term><see cref="Microsoft.PowerShell.EditorServices.Commands.StartEditorServicesCommand"/></term>
+        ///     <description>
+        ///     The StartEditorServicesCommand PSCmdlet, our PowerShell cmdlet written in C# and
+        ///     shipped in the module.
+        ///     </description>
+        /// </item>
+        /// <item>
+        ///     <term><see cref="Microsoft.PowerShell.EditorServices.Commands.StartEditorServicesCommand.EndProcessing"/></term>
+        ///     <description>
+        ///     As a cmdlet, this is the end of its "process" block, and it instantiates <see
+        ///     cref="EditorServicesLoader"/>.
+        ///     </description>
+        /// </item>
+        /// <item>
+        ///     <term><see cref="EditorServicesLoader.LoadAndRunEditorServicesAsync"></term>
+        ///     <description>
+        ///     Loads isolated dependencies then runs and returns the next task.
+        ///     </description>
+        /// </item>
+        /// <item>
+        ///     <term><see cref="RunUntilShutdown"></term>
+        ///     <description>Task which opens a logfile then returns this task.</description>
+        /// </item>
+        /// <item>
+        ///     <term><see cref="CreateEditorServicesAndRunUntilShutdown"></term>
+        ///     <description>This task!</description>
+        /// </item>
+        /// </list>
+        /// </remarks>
         /// <returns>A task that ends when Editor Services shuts down.</returns>
         private async Task CreateEditorServicesAndRunUntilShutdown()
         {