Split classes into their own files; add API docs

This change splits some small classes out into their own files for easier
location.  It also adds missing documentation for many new classes that
were added when debugging support was introduced.

Author: daviwil

src/PowerShellEditorServices.Host/MessageLoop.cs

@@ -104,7 +104,6 @@ async Task ListenForMessages()
 
             // Attach to events from the PowerShell session
             this.editorSession.PowerShellSession.OutputWritten += PowerShellSession_OutputWritten;
-            this.editorSession.PowerShellSession.BreakpointUpdated += PowerShellSession_BreakpointUpdated;
             this.editorSession.DebugService.DebuggerStopped += DebugService_DebuggerStopped;
 
             // Send a "started" event
@@ -184,10 +183,6 @@ await this.messageWriter.WriteMessage(
                 }, null);
         }
 
-        void PowerShellSession_BreakpointUpdated(object sender, BreakpointUpdatedEventArgs e)
-        {
-        }
-
         void PowerShellSession_OutputWritten(object sender, OutputWrittenEventArgs e)
         {
             // TODO: change this to use the OutputEvent!

src/PowerShellEditorServices.Transport.Stdio/Request/ReplExecuteRequest.cs

@@ -16,7 +16,7 @@ public override Task ProcessMessage(
             EditorSession editorSession, 
             MessageWriter messageWriter)
         {
-            editorSession.PowerShellSession.ExecuteScript(
+            editorSession.PowerShellSession.ExecuteScriptString(
                 this.Arguments.CommandString);
 
             return TaskConstants.Completed;

src/PowerShellEditorServices/Analysis/AnalysisService.cs

@@ -22,26 +22,26 @@ public class AnalysisService : IDisposable
 
         private Runspace analysisRunspace;
         private ScriptAnalyzer scriptAnalyzer;
-        private PowerShellSession powerShellSession;
 
         #endregion
 
         #region Constructors
 
         /// <summary>
-        /// Creates an instance of the AnalysisService class with a
-        /// Runspace to use for analysis operations.
+        /// Creates an instance of the AnalysisService class.
         /// </summary>
-        /// <param name="analysisRunspace">
-        /// The Runspace in which analysis operations will be performed.
-        /// </param>
-        public AnalysisService(Runspace analysisRunspace)
+        public AnalysisService()
         {
-            this.analysisRunspace = analysisRunspace;
+            // TODO: Share runspace with PowerShellSession?  Probably should always
+            //       run analysis in a local session.
+            this.analysisRunspace = RunspaceFactory.CreateRunspace(InitialSessionState.CreateDefault2());
+            this.analysisRunspace.ApartmentState = ApartmentState.STA;
+            this.analysisRunspace.ThreadOptions = PSThreadOptions.ReuseThread;
+            this.analysisRunspace.Open();
 
             this.scriptAnalyzer = new ScriptAnalyzer();
             this.scriptAnalyzer.Initialize(
-                analysisRunspace,
+                this.analysisRunspace,
                 new AnalysisOutputWriter(),
                 null,
                 null,
@@ -90,15 +90,19 @@ public ScriptFileMarker[] GetSemanticMarkers(ScriptFile file)
             }
         }
 
-        #endregion
-
+        /// <summary>
+        /// Disposes the runspace being used by the analysis service.
+        /// </summary>
         public void Dispose()
         {
             if (this.analysisRunspace != null)
             {
+                this.analysisRunspace.Close();
                 this.analysisRunspace.Dispose();
                 this.analysisRunspace = null;
             }
         }
+
+        #endregion
     }
 }

src/PowerShellEditorServices/Debugging/BreakpointDetails.cs

@@ -9,10 +9,23 @@
 
 namespace Microsoft.PowerShell.EditorServices
 {
+    /// <summary>
+    /// Provides details about a breakpoint that is set in the
+    /// PowerShell debugger.
+    /// </summary>
     public class BreakpointDetails
     {
-        public int LineNumber { get; set; }
+        /// <summary>
+        /// Gets the line number at which the breakpoint is set.
+        /// </summary>
+        public int LineNumber { get; private set; }
 
+        /// <summary>
+        /// Creates an instance of the BreakpointDetails class from a
+        /// PowerShell Breakpoint object.
+        /// </summary>
+        /// <param name="breakpoint">The Breakpoint instance from which details will be taken.</param>
+        /// <returns>A new instance of the BreakpointDetails class.</returns>
         public static BreakpointDetails Create(Breakpoint breakpoint)
         {
             Validate.IsNotNull("breakpoint", breakpoint);

src/PowerShellEditorServices/Debugging/DebugService.cs

@@ -12,12 +12,15 @@
 
 namespace Microsoft.PowerShell.EditorServices
 {
+    /// <summary>
+    /// Provides a high-level service for interacting with the
+    /// PowerShell debugger in the context of a PowerShellSession.
+    /// </summary>
     public class DebugService
     {
         #region Fields
 
         private PowerShellSession powerShellSession;
-        private ConsoleServicePSHost consoleServicePSHost;
 
         // TODO: This needs to be managed per nested session
         private Dictionary<string, List<Breakpoint>> breakpointsPerFile = 
@@ -31,6 +34,13 @@ public class DebugService
 
         #region Constructors
 
+        /// <summary>
+        /// Initializes a new instance of the DebugService class and uses
+        /// the given PowerShellSession for all future operations.
+        /// </summary>
+        /// <param name="powerShellSession">
+        /// The PowerShellSession to use for all debugging operations.
+        /// </param>
         public DebugService(PowerShellSession powerShellSession)
         {
             Validate.IsNotNull("powerShellSession", powerShellSession);
@@ -44,6 +54,13 @@ public DebugService(PowerShellSession powerShellSession)
 
         #region Public Methods
 
+        /// <summary>
+        /// Sets the list of breakpoints for the current debugging session.
+        /// </summary>
+        /// <param name="scriptFile">The ScriptFile in which breakpoints will be set.</param>
+        /// <param name="lineNumbers">The line numbers at which breakpoints will be set.</param>
+        /// <param name="clearExisting">If true, causes all existing breakpoints to be cleared before setting new ones.</param>
+        /// <returns>An awaitable Task that will provide details about the breakpoints that were set.</returns>
         public async Task<BreakpointDetails[]> SetBreakpoints(
             ScriptFile scriptFile, 
             int[] lineNumbers, 
@@ -76,41 +93,68 @@ await this.powerShellSession.ExecuteCommand<Breakpoint>(
             return new BreakpointDetails[0];
         }
 
+        /// <summary>
+        /// Sends a "continue" action to the debugger when stopped.
+        /// </summary>
         public void Continue()
         {
             this.powerShellSession.ResumeDebugger(
                 DebuggerResumeAction.Continue);
         }
 
+        /// <summary>
+        /// Sends a "step over" action to the debugger when stopped. 
+        /// </summary>
         public void StepOver()
         {
             this.powerShellSession.ResumeDebugger(
                 DebuggerResumeAction.StepOver);
         }
 
+        /// <summary>
+        /// Sends a "step in" action to the debugger when stopped.
+        /// </summary>
         public void StepIn()
         {
             this.powerShellSession.ResumeDebugger(
                 DebuggerResumeAction.StepInto);
         }
 
+        /// <summary>
+        /// Sends a "step out" action to the debugger when stopped.
+        /// </summary>
         public void StepOut()
         {
             this.powerShellSession.ResumeDebugger(
                 DebuggerResumeAction.StepOut);
         }
 
+        /// <summary>
+        /// Causes the debugger to break execution wherever it currently
+        /// is at the time.  This is equivalent to clicking "Pause" in a 
+        /// debugger UI.
+        /// </summary>
         public void Break()
         {
             // Break execution in the debugger
             this.powerShellSession.BreakExecution();
         }
 
-        public void Stop()
+        /// <summary>
+        /// Aborts execution of the debugger while it is running, even while
+        /// it is stopped.  Equivalent to calling PowerShellSession.AbortExecution.
+        /// </summary>
+        public void Abort()
         {
             this.powerShellSession.AbortExecution();
         }
 
+        /// <summary>
+        /// Gets the list of variables that are children of the scope or variable
+        /// that is identified by the given referenced ID.
+        /// </summary>
+        /// <param name="variableReferenceId"></param>
+        /// <returns>An array of VariableDetails instances which describe the requested variables.</returns>
         public VariableDetails[] GetVariables(int variableReferenceId)
         {
             VariableDetails[] childVariables = null;
@@ -148,6 +192,15 @@ public VariableDetails[] GetVariables(int variableReferenceId)
             return childVariables;
         }
 
+        /// <summary>
+        /// Evaluates an expression in the context of the stopped
+        /// debugger.  For now, this just does simple evaluation of
+        /// a variable in the session.  In the future it will execute
+        /// commands in the PowerShellSession.
+        /// </summary>
+        /// <param name="expressionString">The expression string to execute.</param>
+        /// <param name="stackFrameId">The ID of the stack frame in which the expression should be executed.</param>
+        /// <returns>A VariableDetails object containing the result.</returns>
         public VariableDetails EvaluateExpression(string expressionString, int stackFrameId)
         {
             // Break up the variable path
@@ -183,11 +236,24 @@ public VariableDetails EvaluateExpression(string expressionString, int stackFram
             return resolvedVariable;
         }
 
+        /// <summary>
+        /// Gets the list of stack frames at the point where the
+        /// debugger sf stopped.
+        /// </summary>
+        /// <returns>
+        /// An array of StackFrameDetails instances that contain the stack trace.
+        /// </returns>
         public StackFrameDetails[] GetStackFrames()
         {
             return this.callStackFrames;
         }
 
+        /// <summary>
+        /// Gets the list of variable scopes for the stack frame that
+        /// is identified by the given ID.
+        /// </summary>
+        /// <param name="stackFrameId">The ID of the stack frame at which variable scopes should be retrieved.</param>
+        /// <returns>The list of VariableScope instances which describe the available variable scopes.</returns>
         public VariableScope[] GetVariableScopes(int stackFrameId)
         {
             // TODO: Return different scopes based on PowerShell scoping mechanics
@@ -260,6 +326,9 @@ private async Task FetchStackFrames()
 
         #region Events
 
+        /// <summary>
+        /// Raised when the debugger stops execution at a breakpoint or when paused.
+        /// </summary>
         public event EventHandler<DebuggerStopEventArgs> DebuggerStopped;
 
         private async void OnDebuggerStop(object sender, DebuggerStopEventArgs e)
@@ -275,6 +344,9 @@ private async void OnDebuggerStop(object sender, DebuggerStopEventArgs e)
             }
         }
 
+        /// <summary>
+        /// Raised when a breakpoint is added/removed/updated in the debugger.
+        /// </summary>
         public event EventHandler<BreakpointUpdatedEventArgs> BreakpointUpdated;
 
         private void OnBreakpointUpdated(object sender, BreakpointUpdatedEventArgs e)

src/PowerShellEditorServices/Debugging/StackFrameDetails.cs

@@ -8,18 +8,40 @@
 
 namespace Microsoft.PowerShell.EditorServices
 {
+    /// <summary>
+    /// Contains details pertaining to a single stack frame in
+    /// the current debugging session.
+    /// </summary>
     public class StackFrameDetails
     {
+        /// <summary>
+        /// Gets the path to the script where the stack frame occurred.
+        /// </summary>
         public string ScriptPath { get; private set; }
 
+        /// <summary>
+        /// Gets the name of the function where the stack frame occurred.
+        /// </summary>
         public string FunctionName { get; private set; }
 
+        /// <summary>
+        /// Gets the line number of the script where the stack frame occurred.
+        /// </summary>
         public int LineNumber { get; private set; }
 
+        /// <summary>
+        /// Gets the column number of the line where the stack frame occurred.
+        /// </summary>
         public int ColumnNumber { get; private set; }
 
-        public Dictionary<string, PSVariable> LocalVariables { get; private set; }
-
+        /// <summary>
+        /// Creates an instance of the StackFrameDetails class from a
+        /// CallStackFrame instance provided by the PowerShell engine.
+        /// </summary>
+        /// <param name="callStackFrame">
+        /// The original CallStackFrame instance from which details will be obtained.
+        /// </param>
+        /// <returns>A new instance of the StackFrameDetails class.</returns>
         static internal StackFrameDetails Create(
             CallStackFrame callStackFrame)
         {
@@ -31,8 +53,7 @@ static internal StackFrameDetails Create(
                 ScriptPath = callStackFrame.ScriptName,
                 FunctionName = callStackFrame.FunctionName,
                 LineNumber = callStackFrame.Position.StartLineNumber,
-                ColumnNumber = callStackFrame.Position.StartColumnNumber,
-                LocalVariables = callStackFrame.GetFrameVariables()
+                ColumnNumber = callStackFrame.Position.StartColumnNumber
             };
         }
     }