Add XML docs to core packages

Author: SteveSandersonMS

src/Microsoft.AspNetCore.AngularServices/PrimeCacheHelper.cs

@@ -9,14 +9,31 @@
 
 namespace Microsoft.AspNetCore.AngularServices
 {
+    /// <summary>
+    /// Helpers for prepopulating Angular 2's 'http' service with data.
+    /// </summary>
     public static class PrimeCacheHelper
     {
+        /// <summary>
+        /// Performs an HTTP GET request to the specified URL and adds the resulting JSON data
+        /// to the Angular 'http' service cache.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/>.</param>
+        /// <param name="url">The URL to be requested.</param>
+        /// <returns>A task representing the HTML content to be rendered into the document.</returns>
         [Obsolete("Use PrimeCacheAsync instead")]
         public static Task<IHtmlContent> PrimeCache(this IHtmlHelper html, string url)
         {
             return PrimeCacheAsync(html, url);
         }
 
+        /// <summary>
+        /// Performs an HTTP GET request to the specified URL and adds the resulting JSON data
+        /// to the Angular 'http' service cache.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/>.</param>
+        /// <param name="url">The URL to be requested.</param>
+        /// <returns>A task representing the HTML content to be rendered into the document.</returns>
         public static async Task<IHtmlContent> PrimeCacheAsync(this IHtmlHelper html, string url)
         {
             // TODO: Consider deduplicating the PrimeCacheAsync calls (that is, if there are multiple requests to precache

src/Microsoft.AspNetCore.AngularServices/project.json

@@ -14,7 +14,8 @@
   },
   "buildOptions": {
     "warningsAsErrors": true,
-    "keyFile": "../../tools/Key.snk"
+    "keyFile": "../../tools/Key.snk",
+    "xmlDoc": true
   },
   "dependencies": {
     "Microsoft.AspNetCore.Mvc.TagHelpers": "1.0.1",

src/Microsoft.AspNetCore.NodeServices/Configuration/NodeHostingModel.cs

@@ -1,8 +1,18 @@
 namespace Microsoft.AspNetCore.NodeServices
 {
+    /// <summary>
+    /// Represents a way of creating and invoking code in a Node.js environment.
+    /// </summary>
     public enum NodeHostingModel
     {
+        /// <summary>
+        /// An out-of-process Node.js instance where RPC calls are made via HTTP.
+        /// </summary>
         Http,
+
+        /// <summary>
+        /// An out-of-process Node.js instance where RPC calls are made over binary sockets.
+        /// </summary>
         Socket,
     }
 }

src/Microsoft.AspNetCore.NodeServices/Configuration/NodeServicesFactory.cs

@@ -3,8 +3,16 @@
 
 namespace Microsoft.AspNetCore.NodeServices
 {
+    /// <summary>
+    /// Supplies INodeServices instances.
+    /// </summary>
     public static class NodeServicesFactory
     {
+        /// <summary>
+        /// Create an <see cref="INodeServices"/> instance according to the supplied options.
+        /// </summary>
+        /// <param name="options">Options for creating the <see cref="INodeServices"/> instance.</param>
+        /// <returns>An <see cref="INodeServices"/> instance.</returns>
         public static INodeServices CreateNodeServices(NodeServicesOptions options)
         {
             if (options == null)

src/Microsoft.AspNetCore.NodeServices/Configuration/NodeServicesOptions.cs

@@ -8,14 +8,25 @@
 
 namespace Microsoft.AspNetCore.NodeServices
 {
+    /// <summary>
+    /// Describes options used to configure an <see cref="INodeServices"/> instance.
+    /// </summary>
     public class NodeServicesOptions
     {
+        /// <summary>
+        /// Defines the default <see cref="NodeHostingModel"/>.
+        /// </summary>
         public const NodeHostingModel DefaultNodeHostingModel = NodeHostingModel.Http;
+
         internal const string TimeoutConfigPropertyName = nameof(InvocationTimeoutMilliseconds);
         private const int DefaultInvocationTimeoutMilliseconds = 60 * 1000;
         private const string LogCategoryName = "Microsoft.AspNetCore.NodeServices";
         private static readonly string[] DefaultWatchFileExtensions = { ".js", ".jsx", ".ts", ".tsx", ".json", ".html" };
 
+        /// <summary>
+        /// Creates a new instance of <see cref="NodeServicesOptions"/>.
+        /// </summary>
+        /// <param name="serviceProvider">The <see cref="IServiceProvider"/>.</param>
         public NodeServicesOptions(IServiceProvider serviceProvider)
         {
             if (serviceProvider == null)
@@ -44,14 +55,49 @@ public NodeServicesOptions(IServiceProvider serviceProvider)
                 : new ConsoleLogger(LogCategoryName, null, false);
         }
 
+        /// <summary>
+        /// Specifies which <see cref="NodeHostingModel"/> should be used.
+        /// </summary>
         public NodeHostingModel HostingModel { get; set; }
+
+        /// <summary>
+        /// If set, this callback function will be invoked to supply the <see cref="INodeServices"/> instance.
+        /// </summary>
         public Func<INodeInstance> NodeInstanceFactory { get; set; }
+
+        /// <summary>
+        /// If set, overrides the path to the root of your application. This path is used when locating Node.js modules relative to your project.
+        /// </summary>
         public string ProjectPath { get; set; }
+
+        /// <summary>
+        /// If set, the Node.js instance should restart when any matching file on disk within your project changes.
+        /// </summary>
         public string[] WatchFileExtensions { get; set; }
+
+        /// <summary>
+        /// The Node.js instance's stdout/stderr will be redirected to this <see cref="ILogger"/>.
+        /// </summary>
         public ILogger NodeInstanceOutputLogger { get; set; }
+
+        /// <summary>
+        /// If true, the Node.js instance will accept incoming V8 debugger connections (e.g., from node-inspector).
+        /// </summary>
         public bool LaunchWithDebugging { get; set; }
-        public IDictionary<string, string> EnvironmentVariables { get; set; }
+
+        /// <summary>
+        /// If <see cref="LaunchWithDebugging"/> is true, the Node.js instance will listen for V8 debugger connections on this port.
+        /// </summary>
         public int DebuggingPort { get; set; }
+
+        /// <summary>
+        /// If set, starts the Node.js instance with the specified environment variables.
+        /// </summary>
+        public IDictionary<string, string> EnvironmentVariables { get; set; }
+
+        /// <summary>
+        /// Specifies the maximum duration, in milliseconds, that your .NET code should wait for Node.js RPC calls to return.
+        /// </summary>
         public int InvocationTimeoutMilliseconds { get; set; }
     }
 }

src/Microsoft.AspNetCore.NodeServices/Configuration/NodeServicesServiceCollectionExtensions.cs

@@ -8,9 +8,18 @@ namespace Microsoft.Extensions.DependencyInjection
     /// </summary>
     public static class NodeServicesServiceCollectionExtensions
     {
+        /// <summary>
+        /// Adds NodeServices support to the <paramref name="serviceCollection"/>.
+        /// </summary>
+        /// <param name="serviceCollection">The <see cref="IServiceCollection"/>.</param>
         public static void AddNodeServices(this IServiceCollection serviceCollection)
             => AddNodeServices(serviceCollection, _ => {});
 
+        /// <summary>
+        /// Adds NodeServices support to the <paramref name="serviceCollection"/>.
+        /// </summary>
+        /// <param name="serviceCollection">The <see cref="IServiceCollection"/>.</param>
+        /// <param name="options">Options for configuring the <see cref="INodeServices"/> instances.</param>
         [Obsolete("Use the AddNodeServices(Action<NodeServicesOptions> setupAction) overload instead.")]
         public static void AddNodeServices(this IServiceCollection serviceCollection, NodeServicesOptions options)
         {
@@ -20,6 +29,11 @@ public static void AddNodeServices(this IServiceCollection serviceCollection, No
             });
         }
 
+        /// <summary>
+        /// Adds NodeServices support to the <paramref name="serviceCollection"/>.
+        /// </summary>
+        /// <param name="serviceCollection">The <see cref="IServiceCollection"/>.</param>
+        /// <param name="setupAction">A callback that will be invoked to populate the <see cref="NodeServicesOptions"/>.</param>
         public static void AddNodeServices(this IServiceCollection serviceCollection, Action<NodeServicesOptions> setupAction)
         {
             if (setupAction == null)

src/Microsoft.AspNetCore.NodeServices/HostingModels/INodeInstance.cs

@@ -4,8 +4,20 @@
 
 namespace Microsoft.AspNetCore.NodeServices.HostingModels
 {
+    /// <summary>
+    /// Represents an instance of Node.js to which Remote Procedure Calls (RPC) may be sent.
+    /// </summary>
     public interface INodeInstance : IDisposable
     {
+        /// <summary>
+        /// Asynchronously invokes code in the Node.js instance.
+        /// </summary>
+        /// <typeparam name="T">The JSON-serializable data type that the Node.js code will asynchronously return.</typeparam>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the invocation.</param>
+        /// <param name="moduleName">The path to the Node.js module (i.e., JavaScript file) relative to your project root that contains the code to be invoked.</param>
+        /// <param name="exportNameOrNull">If set, specifies the CommonJS export to be invoked. If not set, the module's default CommonJS export itself must be a function to be invoked.</param>
+        /// <param name="args">Any sequence of JSON-serializable arguments to be passed to the Node.js function.</param>
+        /// <returns>A <see cref="Task{TResult}"/> representing the completion of the RPC call.</returns>
         Task<T> InvokeExportAsync<T>(CancellationToken cancellationToken, string moduleName, string exportNameOrNull, params object[] args);
     }
 }

src/Microsoft.AspNetCore.NodeServices/HostingModels/NodeInvocationException.cs

@@ -2,15 +2,33 @@
 
 namespace Microsoft.AspNetCore.NodeServices.HostingModels
 {
+    /// <summary>
+    /// Represents an exception caused by invoking Node.js code.
+    /// </summary>
     public class NodeInvocationException : Exception
     {
+        /// <summary>
+        /// If true, indicates that the invocation failed because the Node.js instance could not be reached. For example,
+        /// it might have already shut down or previously crashed.
+        /// </summary>
         public bool NodeInstanceUnavailable { get; private set; }
 
+        /// <summary>
+        /// Creates a new instance of <see cref="NodeInvocationException"/>.
+        /// </summary>
+        /// <param name="message">A description of the exception.</param>
+        /// <param name="details">Additional information, such as a Node.js stack trace, representing the exception.</param>
         public NodeInvocationException(string message, string details)
             : base(message + Environment.NewLine + details)
         {
         }
 
+        /// <summary>
+        /// Creates a new instance of <see cref="NodeInvocationException"/>.
+        /// </summary>
+        /// <param name="message">A description of the exception.</param>
+        /// <param name="details">Additional information, such as a Node.js stack trace, representing the exception.</param>
+        /// <param name="nodeInstanceUnavailable">Specifies a value for the <see cref="NodeInstanceUnavailable"/> flag.</param>
         public NodeInvocationException(string message, string details, bool nodeInstanceUnavailable)
             : this(message, details)
         {

src/Microsoft.AspNetCore.NodeServices/HostingModels/NodeInvocationInfo.cs

@@ -1,9 +1,24 @@
 namespace Microsoft.AspNetCore.NodeServices.HostingModels
 {
+    /// <summary>
+    /// Describes an RPC call sent from .NET code to Node.js code.
+    /// </summary>
     public class NodeInvocationInfo
     {
+        /// <summary>
+        /// Specifies the path to the Node.js module (i.e., .js file) relative to the project root.
+        /// </summary>
         public string ModuleName { get; set; }
+
+        /// <summary>
+        /// If set, specifies the name of CommonJS function export to be invoked.
+        /// If not set, the Node.js module's default export must itself be a function to be invoked.
+        /// </summary>
         public string ExportedFunctionName { get; set; }
+
+        /// <summary>
+        /// A sequence of JSON-serializable arguments to be passed to the Node.js function being invoked.
+        /// </summary>
         public object[] Args { get; set; }
     }
 }

src/Microsoft.AspNetCore.NodeServices/HostingModels/OutOfProcessNodeInstance.cs

@@ -21,7 +21,11 @@ namespace Microsoft.AspNetCore.NodeServices.HostingModels
     /// <seealso cref="Microsoft.AspNetCore.NodeServices.HostingModels.INodeInstance" />
     public abstract class OutOfProcessNodeInstance : INodeInstance
     {
+        /// <summary>
+        /// The <see cref="ILogger"/> to which the Node.js instance's stdout/stderr is being redirected.
+        /// </summary>
         protected readonly ILogger OutputLogger;
+
         private const string ConnectionEstablishedMessage = "[Microsoft.AspNetCore.NodeServices:Listening]";
         private const string DebuggingStartedMessageFormat = @"-----
 *** Node.js debugging is enabled ***
@@ -43,6 +47,18 @@ npm install -g node-inspector
         private bool _nodeProcessNeedsRestart;
         private readonly string[] _watchFileExtensions;
 
+        /// <summary>
+        /// Creates a new instance of <see cref="OutOfProcessNodeInstance"/>.
+        /// </summary>
+        /// <param name="entryPointScript">The path to the entry point script that the Node instance should load and execute.</param>
+        /// <param name="projectPath">The root path of the current project. This is used when resolving Node.js module paths relative to the project root.</param>
+        /// <param name="watchFileExtensions">The filename extensions that should be watched within the project root. The Node instance will automatically shut itself down if any matching file changes.</param>
+        /// <param name="commandLineArguments">Additional command-line arguments to be passed to the Node.js instance.</param>
+        /// <param name="nodeOutputLogger">The <see cref="ILogger"/> to which the Node.js instance's stdout/stderr (and other log information) should be written.</param>
+        /// <param name="environmentVars">Environment variables to be set on the Node.js process.</param>
+        /// <param name="invocationTimeoutMilliseconds">The maximum duration, in milliseconds, to wait for RPC calls to complete.</param>
+        /// <param name="launchWithDebugging">If true, passes a flag to the Node.js process telling it to accept V8 debugger connections.</param>
+        /// <param name="debuggingPort">If debugging is enabled, the Node.js process should listen for V8 debugger connections on this port.</param>
         public OutOfProcessNodeInstance(
             string entryPointScript,
             string projectPath,
@@ -71,6 +87,15 @@ public OutOfProcessNodeInstance(
             ConnectToInputOutputStreams();
         }
 
+        /// <summary>
+        /// Asynchronously invokes code in the Node.js instance.
+        /// </summary>
+        /// <typeparam name="T">The JSON-serializable data type that the Node.js code will asynchronously return.</typeparam>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the invocation.</param>
+        /// <param name="moduleName">The path to the Node.js module (i.e., JavaScript file) relative to your project root that contains the code to be invoked.</param>
+        /// <param name="exportNameOrNull">If set, specifies the CommonJS export to be invoked. If not set, the module's default CommonJS export itself must be a function to be invoked.</param>
+        /// <param name="args">Any sequence of JSON-serializable arguments to be passed to the Node.js function.</param>
+        /// <returns>A <see cref="Task{TResult}"/> representing the completion of the RPC call.</returns>
         public async Task<T> InvokeExportAsync<T>(
             CancellationToken cancellationToken, string moduleName, string exportNameOrNull, params object[] args)
         {
@@ -154,21 +179,41 @@ public async Task<T> InvokeExportAsync<T>(
             }
         }
 
+        /// <summary>
+        /// Disposes this instance.
+        /// </summary>
         public void Dispose()
         {
             Dispose(true);
             GC.SuppressFinalize(this);
         }
 
+        /// <summary>
+        /// Asynchronously invokes code in the Node.js instance.
+        /// </summary>
+        /// <typeparam name="T">The JSON-serializable data type that the Node.js code will asynchronously return.</typeparam>
+        /// <param name="invocationInfo">Specifies the Node.js function to be invoked and arguments to be passed to it.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the invocation.</param>
+        /// <returns>A <see cref="Task{TResult}"/> representing the completion of the RPC call.</returns>
         protected abstract Task<T> InvokeExportAsync<T>(
             NodeInvocationInfo invocationInfo,
             CancellationToken cancellationToken);
 
-        // This method is virtual, as it provides a way to override the NODE_PATH or the path to node.exe
+        /// <summary>
+        /// Configures a <see cref="ProcessStartInfo"/> instance describing how to launch the Node.js process.
+        /// </summary>
+        /// <param name="entryPointFilename">The entrypoint JavaScript file that the Node.js process should execute.</param>
+        /// <param name="projectPath">The root path of the project. This is used when locating Node.js modules relative to the project root.</param>
+        /// <param name="commandLineArguments">Command-line arguments to be passed to the Node.js process.</param>
+        /// <param name="environmentVars">Environment variables to be set on the Node.js process.</param>
+        /// <param name="launchWithDebugging">If true, passes a flag to the Node.js process telling it to accept V8 debugger connections.</param>
+        /// <param name="debuggingPort">If debugging is enabled, the Node.js process should listen for V8 debugger connections on this port.</param>
+        /// <returns></returns>
         protected virtual ProcessStartInfo PrepareNodeProcessStartInfo(
             string entryPointFilename, string projectPath, string commandLineArguments,
             IDictionary<string, string> environmentVars, bool launchWithDebugging, int debuggingPort)
         {
+            // This method is virtual, as it provides a way to override the NODE_PATH or the path to node.exe
             string debuggingArgs;
             if (launchWithDebugging)
             {
@@ -217,16 +262,28 @@ protected virtual ProcessStartInfo PrepareNodeProcessStartInfo(
             return startInfo;
         }
 
+        /// <summary>
+        /// Virtual method invoked whenever the Node.js process emits a line to its stdout.
+        /// </summary>
+        /// <param name="outputData">The line emitted to the Node.js process's stdout.</param>
         protected virtual void OnOutputDataReceived(string outputData)
         {
             OutputLogger.LogInformation(outputData);
         }
 
+        /// <summary>
+        /// Virtual method invoked whenever the Node.js process emits a line to its stderr.
+        /// </summary>
+        /// <param name="errorData">The line emitted to the Node.js process's stderr.</param>
         protected virtual void OnErrorDataReceived(string errorData)
         {
             OutputLogger.LogError(errorData);
         }
 
+        /// <summary>
+        /// Disposes the instance.
+        /// </summary>
+        /// <param name="disposing">True if the object is disposing or false if it is finalizing.</param>
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)
@@ -403,6 +460,9 @@ private void RestartDueToFileChange(string fullPath)
             EnsureFileSystemWatcherIsDisposed();
         }
 
+        /// <summary>
+        /// Implements the finalization part of the IDisposable pattern by calling Dispose(false).
+        /// </summary>
         ~OutOfProcessNodeInstance()
         {
             Dispose(false);