Finish public interface comments for core library

This change also makes XML comments mandatory on all public
interfaces for Release builds of the core library project.

Author: daviwil

src/PowerShellEditorServices/Console/ConsoleService.cs

@@ -30,6 +30,19 @@ public class ConsoleService : IDisposable
 
         #region Constructors
 
+        /// <summary>
+        /// Creates an instance of the ConsoleService class using the
+        /// given IConsoleHost implementation to invoke host operations
+        /// on behalf of the ConsolePSHost.  An InitialSessionState may
+        /// be provided to create the console runspace using a particular
+        /// configuraiton.
+        /// </summary>
+        /// <param name="consoleHost">
+        /// An IConsoleHost implementation which handles host operations.
+        /// </param>
+        /// <param name="initialSessionState">
+        /// An optional InitialSessionState to use in creating the console runspace.
+        /// </param>
         public ConsoleService(
             IConsoleHost consoleHost, 
             InitialSessionState initialSessionState = null)
@@ -56,6 +69,11 @@ public ConsoleService(
 
         #region Public Methods
 
+        /// <summary>
+        /// Executes a command in the console runspace.
+        /// </summary>
+        /// <param name="commandString">The command string to execute.</param>
+        /// <returns>A Task that can be awaited for the command completion.</returns>
         public async Task ExecuteCommand(string commandString)
         {
             PowerShell powerShell = PowerShell.Create();
@@ -101,6 +119,15 @@ await Task.Factory.StartNew(
             }
         }
 
+        /// <summary>
+        /// Sends a user's prompt choice response back to the specified prompt ID.
+        /// </summary>
+        /// <param name="promptId">
+        /// The ID of the prompt to which the user is responding.
+        /// </param>
+        /// <param name="choiceResult">
+        /// The index of the choice that the user selected.
+        /// </param>
         public void ReceiveChoicePromptResult(
             int promptId, 
             int choiceResult)
@@ -109,6 +136,10 @@ public void ReceiveChoicePromptResult(
             this.consoleHost.PromptForChoiceResult(promptId, choiceResult);
         }
 
+        /// <summary>
+        /// Sends a CTRL+C signal to the console to halt execution of
+        /// the current command.
+        /// </summary>
         public void SendControlC()
         {
             // TODO: Cancel the current pipeline execution
@@ -118,6 +149,9 @@ public void SendControlC()
 
         #region IDisposable Implementation
 
+        /// <summary>
+        /// Disposes the runspace in use by the ConsoleService.
+        /// </summary>
         public void Dispose()
         {
             if (this.currentRunspace != null)

src/PowerShellEditorServices/Console/IConsoleHost.cs

@@ -47,28 +47,39 @@ void WriteOutput(
         /// <summary>
         /// Prompts the user to make a choice using the provided details.
         /// </summary>
-        /// <param name="caption">
+        /// <param name="promptCaption">
         /// The caption string which will be displayed to the user.
         /// </param>
-        /// <param name="message">
+        /// <param name="promptMessage">
         /// The descriptive message which will be displayed to the user.
         /// </param>
-        /// <param name="choices">
+        /// <param name="choiceDescriptions">
         /// The list of choices from which the user will select.
         /// </param>
         /// <param name="defaultChoice">
         /// The default choice to highlight for the user.
         /// </param>
         /// <returns>
         /// A Task instance that can be monitored for completion to get
-        /// the user's choice.</returns>
+        /// the user's choice.
+        /// </returns>
         Task<int> PromptForChoice(
             string promptCaption,
             string promptMessage,
             IEnumerable<ChoiceDescription> choiceDescriptions,
             int defaultChoice);
 
-        // TODO: Get rid of this!
+        // TODO: Get rid of this method!  Leaky abstraction.
+
+        /// <summary>
+        /// Sends a user's prompt choice response back to the specified prompt ID.
+        /// </summary>
+        /// <param name="promptId">
+        /// The ID of the prompt to which the user is responding.
+        /// </param>
+        /// <param name="choiceResult">
+        /// The index of the choice that the user selected.
+        /// </param>
         void PromptForChoiceResult(
             int promptId,
             int choiceResult);

src/PowerShellEditorServices/Console/SynchronizingConsoleHostWrapper.cs

@@ -31,6 +31,18 @@ public class SynchronizingConsoleHostWrapper : IConsoleHost
 
         #region Constructors
 
+        /// <summary>
+        /// Creates an instance of the SynchronizingConsoleHostWrapper
+        /// class that wraps the given IConsoleHost implementation and
+        /// invokes its calls through the given SynchronizationContext.
+        /// </summary>
+        /// <param name="wrappedConsoleHost">
+        /// The IConsoleHost implementation that will be wrapped.
+        /// </param>
+        /// <param name="syncContext">
+        /// The SynchronizationContext which will be used for invoking
+        /// host operations calls on the proper thread.
+        /// </param>
         public SynchronizingConsoleHostWrapper(
             IConsoleHost wrappedConsoleHost,
             SynchronizationContext syncContext)

src/PowerShellEditorServices/Language/AstOperations.cs

@@ -16,6 +16,26 @@ namespace Microsoft.PowerShell.EditorServices.Language
     /// </summary>
     public static class AstOperations
     {
+        /// <summary>
+        /// Gets completions for the symbol found in the Ast at 
+        /// the given file offset.
+        /// </summary>
+        /// <param name="scriptAst">
+        /// The Ast which will be traversed to find a completable symbol.
+        /// </param>
+        /// <param name="currentTokens">
+        /// The array of tokens corresponding to the scriptAst parameter.
+        /// </param>
+        /// <param name="fileOffset">
+        /// The 1-based file offset at which a symbol will be located.
+        /// </param>
+        /// <param name="runspace">
+        /// The Runspace to use for gathering completions.
+        /// </param>
+        /// <returns>
+        /// A CommandCompletion instance that contains completions for the
+        /// symbol at the given offset.
+        /// </returns>
         static public CommandCompletion GetCompletions(
             Ast scriptAst, 
             Token[] currentTokens, 

src/PowerShellEditorServices/Language/LanguageService.cs

@@ -13,17 +13,54 @@ namespace Microsoft.PowerShell.EditorServices.Language
     using System.Management.Automation;
     using System.Management.Automation.Runspaces;
 
+    /// <summary>
+    /// Provides a high-level service for performing code completion and
+    /// navigation operations on PowerShell scripts.
+    /// </summary>
     public class LanguageService
     {
+        #region Private Fields
+
         private Runspace runspace;
 
+        #endregion
+
+        #region Constructors
+
+        /// <summary>
+        /// Constructs an instance of the LanguageService class and uses
+        /// the given Runspace to execute language service operations.
+        /// </summary>
+        /// <param name="languageServiceRunspace">
+        /// The Runspace in which language service operations will be executed.
+        /// </param>
         public LanguageService(Runspace languageServiceRunspace)
         {
             Validate.IsNotNull("languageServiceRunspace", languageServiceRunspace);
 
             this.runspace = languageServiceRunspace;
         }
 
+        #endregion
+
+        #region Public Methods
+
+        /// <summary>
+        /// Gets completions for a statement contained in the given
+        /// script file at the specified line and column position.
+        /// </summary>
+        /// <param name="scriptFile">
+        /// The script file in which completions will be gathered.
+        /// </param>
+        /// <param name="lineNumber">
+        /// The 1-based line number at which completions will be gathered.
+        /// </param>
+        /// <param name="columnNumber">
+        /// The 1-based column number at which completions will be gathered.
+        /// </param>
+        /// <returns>
+        /// A CommandCompletion instance completions for the identified statement.
+        /// </returns>
         public CommandCompletion GetCompletionsInFile(
             ScriptFile scriptFile,
             int lineNumber,
@@ -47,5 +84,7 @@ public CommandCompletion GetCompletionsInFile(
 
             return completionSuggestions;
         }
+
+        #endregion
     }
 }

src/PowerShellEditorServices/Language/ScriptExtent.cs

@@ -12,63 +12,101 @@
 
 namespace Microsoft.PowerShell.EditorServices.Language
 {
+    /// <summary>
+    /// Provides a default IScriptExtent implementation
+    /// containing details about a section of script content
+    /// in a file.
+    /// </summary>
     public class ScriptExtent : IScriptExtent
     {
-        public int EndColumnNumber
+        #region Properties
+
+        /// <summary>
+        /// Gets the file path of the script file in which this extent is contained.
+        /// </summary>
+        public string File
+        {
+            get { throw new NotImplementedException(); }
+        }
+
+        /// <summary>
+        /// Gets or sets the starting column number of the extent.
+        /// </summary>
+        public int StartColumnNumber
         {
             get;
             set;
         }
 
-        public int EndLineNumber
+        /// <summary>
+        /// Gets or sets the starting line number of the extent.
+        /// </summary>
+        public int StartLineNumber
         {
             get;
             set;
         }
 
-        public int EndOffset
+        /// <summary>
+        /// Gets or sets the starting file offset of the extent.
+        /// </summary>
+        public int StartOffset
         {
             get;
             set;
         }
 
-        public IScriptPosition EndScriptPosition
+        /// <summary>
+        /// Gets or sets the starting script position of the extent.
+        /// </summary>
+        public IScriptPosition StartScriptPosition
         {
             get { throw new NotImplementedException(); }
         }
-
-        public string File
+        /// <summary>
+        /// Gets or sets the text that is contained within the extent.
+        /// </summary>
+        public string Text
         {
-            get { throw new NotImplementedException(); }
+            get;
+            set;
         }
 
-        public int StartColumnNumber
+        /// <summary>
+        /// Gets or sets the ending column number of the extent.
+        /// </summary>
+        public int EndColumnNumber
         {
             get;
             set;
         }
 
-        public int StartLineNumber
+        /// <summary>
+        /// Gets or sets the ending line number of the extent.
+        /// </summary>
+        public int EndLineNumber
         {
             get;
             set;
         }
 
-        public int StartOffset
+        /// <summary>
+        /// Gets or sets the ending file offset of the extent.
+        /// </summary>
+        public int EndOffset
         {
             get;
             set;
         }
 
-        public IScriptPosition StartScriptPosition
+        /// <summary>
+        /// Gets the ending script position of the extent.
+        /// </summary>
+        public IScriptPosition EndScriptPosition
         {
             get { throw new NotImplementedException(); }
         }
 
-        public string Text
-        {
-            get;
-            set;
-        }
+        #endregion
     }
 }

src/PowerShellEditorServices/PowerShellEditorServices.csproj

@@ -31,6 +31,8 @@
     <DefineConstants>TRACE</DefineConstants>
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
+    <WarningsAsErrors>1591,1573,1572</WarningsAsErrors>
+    <DocumentationFile>bin\Release\Microsoft.PowerShell.EditorServices.XML</DocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="Nito.AsyncEx, Version=3.0.0.0, Culture=neutral, processorArchitecture=MSIL">

src/PowerShellEditorServices/Session/EditorSession.cs

@@ -123,6 +123,10 @@ public IEnumerable<ScriptFile> GetOpenFiles()
 
         #region IDisposable Implementation
 
+        /// <summary>
+        /// Disposes of any Runspaces that were created for the
+        /// services used in this session.
+        /// </summary>
         public void Dispose()
         {
             // Dispose all necessary services