Add OWIN docs (#28947)

Co-authored-by: Pranav K <prkrishn@hotmail.com>
Co-authored-by: Chris Ross <Tratcher@Outlook.com>

Author: 3 people

src/Http/Owin/src/IOwinEnvironmentFeature.cs

@@ -5,8 +5,14 @@
 
 namespace Microsoft.AspNetCore.Owin
 {
+    /// <summary>
+    /// A feature interface for an OWIN environment.
+    /// </summary>
     public interface IOwinEnvironmentFeature
     {
+        /// <summary>
+        /// Gets or sets the environment values.
+        /// </summary>
         IDictionary<string, object> Environment { get; set; }
     }
-}
+}

src/Http/Owin/src/Microsoft.AspNetCore.Owin.csproj

@@ -3,7 +3,6 @@
   <PropertyGroup>
     <Description>ASP.NET Core component for running OWIN middleware in an ASP.NET Core application, and to run ASP.NET Core middleware in an OWIN application.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;owin</PackageTags>
   </PropertyGroup>

src/Http/Owin/src/OwinEnvironment.cs

@@ -28,11 +28,18 @@ namespace Microsoft.AspNetCore.Owin
             Task<WebSocket>
         >;
 
+    /// <summary>
+    /// A loosely-typed OWIN environment wrapper over an <see cref="HttpContext"/>.
+    /// </summary>
     public class OwinEnvironment : IDictionary<string, object>
     {
         private HttpContext _context;
         private IDictionary<string, FeatureMap> _entries;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="OwinEnvironment"/>.
+        /// </summary>
+        /// <param name="context">The request context.</param>
         public OwinEnvironment(HttpContext context)
         {
             if (context.Features.Get<IHttpRequestFeature>() == null)
@@ -131,6 +138,9 @@ public OwinEnvironment(HttpContext context)
         }
 
         // Public in case there's a new/custom feature interface that needs to be added.
+        /// <summary>
+        /// Get the environment's feature maps.
+        /// </summary>
         public IDictionary<string, FeatureMap> FeatureMaps
         {
             get { return _entries; }
@@ -269,6 +279,7 @@ bool ICollection<KeyValuePair<string, object>>.Remove(KeyValuePair<string, objec
             throw new NotImplementedException();
         }
 
+        /// <inheritdoc />
         public IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         {
             foreach (var entryPair in _entries)
@@ -290,27 +301,63 @@ IEnumerator IEnumerable.GetEnumerator()
             return GetEnumerator();
         }
 
+        /// <summary>
+        /// Maps OWIN keys to ASP.NET Core features.
+        /// </summary>
         public class FeatureMap
         {
+            /// <summary>
+            /// Create a <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="featureInterface">The feature interface type.</param>
+            /// <param name="getter">Value getter.</param>
             public FeatureMap(Type featureInterface, Func<object, object> getter)
                 : this(featureInterface, getter, defaultFactory: null)
             {
             }
+
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="featureInterface">The feature interface type.</param>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
             public FeatureMap(Type featureInterface, Func<object, object> getter, Func<object> defaultFactory)
                 : this(featureInterface, getter, defaultFactory, setter: null)
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="featureInterface">The feature interface type.</param>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
             public FeatureMap(Type featureInterface, Func<object, object> getter, Action<object, object> setter)
                 : this(featureInterface, getter, defaultFactory: null, setter: setter)
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="featureInterface">The feature interface type.</param>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
             public FeatureMap(Type featureInterface, Func<object, object> getter, Func<object> defaultFactory, Action<object, object> setter)
                 : this(featureInterface, getter, defaultFactory, setter, featureFactory: null)
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="featureInterface">The feature interface type.</param>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
+            /// <param name="featureFactory">Feature factory delegate.</param>
             public FeatureMap(Type featureInterface, Func<object, object> getter, Func<object> defaultFactory, Action<object, object> setter, Func<object> featureFactory)
             {
                 FeatureInterface = featureInterface;
@@ -326,6 +373,9 @@ public FeatureMap(Type featureInterface, Func<object, object> getter, Func<objec
             private Func<object> DefaultFactory { get; set; }
             private Func<object> FeatureFactory { get; set; }
 
+            /// <summary>
+            /// Gets a value indicating whether the feature map is settable.
+            /// </summary>
             public bool CanSet
             {
                 get { return Setter != null; }
@@ -366,28 +416,59 @@ internal void Set(HttpContext context, object value)
             }
         }
 
+        /// <summary>
+        /// Maps OWIN keys to ASP.NET Core features.
+        /// </summary>
+        /// <typeparam name="TFeature">Feature interface type.</typeparam>
         public class FeatureMap<TFeature> : FeatureMap
         {
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="getter">Value getter.</param>
             public FeatureMap(Func<TFeature, object> getter)
                 : base(typeof(TFeature), feature => getter((TFeature)feature))
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
             public FeatureMap(Func<TFeature, object> getter, Func<object> defaultFactory)
                 : base(typeof(TFeature), feature => getter((TFeature)feature), defaultFactory)
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
             public FeatureMap(Func<TFeature, object> getter, Action<TFeature, object> setter)
                 : base(typeof(TFeature), feature => getter((TFeature)feature), (feature, value) => setter((TFeature)feature, value))
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
             public FeatureMap(Func<TFeature, object> getter, Func<object> defaultFactory, Action<TFeature, object> setter)
                 : base(typeof(TFeature), feature => getter((TFeature)feature), defaultFactory, (feature, value) => setter((TFeature)feature, value))
             {
             }
 
+            /// <summary>
+            /// Initializes a new instance of <see cref="FeatureMap"/> for the specified feature interface type.
+            /// </summary>
+            /// <param name="getter">Value getter delegate.</param>
+            /// <param name="defaultFactory">Default value factory delegate.</param>
+            /// <param name="setter">Value setter delegate.</param>
+            /// <param name="featureFactory">Feature factory delegate.</param>
             public FeatureMap(Func<TFeature, object> getter, Func<object> defaultFactory, Action<TFeature, object> setter, Func<TFeature> featureFactory)
                 : base(typeof(TFeature), feature => getter((TFeature)feature), defaultFactory, (feature, value) => setter((TFeature)feature, value), () => featureFactory())
             {

src/Http/Owin/src/OwinEnvironmentFeature.cs

@@ -5,8 +5,12 @@
 
 namespace Microsoft.AspNetCore.Owin
 {
+    /// <summary>
+    /// Default implementation of <see cref="IOwinEnvironmentFeature"/>.
+    /// </summary>
     public class OwinEnvironmentFeature : IOwinEnvironmentFeature
     {
+        /// <inheritdoc />
         public IDictionary<string, object> Environment { get; set; }
     }
-}
+}

src/Http/Owin/src/OwinExtensions.cs

@@ -20,8 +20,16 @@ namespace Microsoft.AspNetCore.Builder
           Func<IDictionary<string, object>, Task>
         >;
 
+    /// <summary>
+    /// Extension methods to add OWIN to an HTTP application pipeline.
+    /// </summary>
     public static class OwinExtensions
     {
+        /// <summary>
+        /// Adds an OWIN pipeline to the specified <see cref="IApplicationBuilder"/>.
+        /// </summary>
+        /// <param name="builder">The <see cref="IApplicationBuilder"/> to add the pipeline to.</param>
+        /// <returns>An action used to create the OWIN pipeline.</returns>
         public static AddMiddleware UseOwin(this IApplicationBuilder builder)
         {
             if (builder == null)
@@ -62,6 +70,12 @@ public static AddMiddleware UseOwin(this IApplicationBuilder builder)
             return add;
         }
 
+        /// <summary>
+        /// Adds OWIN middleware pipeline to the specified <see cref="IApplicationBuilder"/>.
+        /// </summary>
+        /// <param name="builder">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="pipeline">A delegate which can specify the OWIN pipeline.</param>
+        /// <returns>The original <see cref="IApplicationBuilder"/>.</returns>
         public static IApplicationBuilder UseOwin(this IApplicationBuilder builder, Action<AddMiddleware> pipeline)
         {
             if (builder == null)
@@ -77,11 +91,22 @@ public static IApplicationBuilder UseOwin(this IApplicationBuilder builder, Acti
             return builder;
         }
 
+        /// <summary>
+        /// Creates an <see cref="IApplicationBuilder"/> for an OWIN pipeline.
+        /// </summary>
+        /// <param name="app">The OWIN pipeline.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/></returns>
         public static IApplicationBuilder UseBuilder(this AddMiddleware app)
         {
             return app.UseBuilder(serviceProvider: null);
         }
 
+        /// <summary>
+        /// Creates an <see cref="IApplicationBuilder"/> for an OWIN pipeline.
+        /// </summary>
+        /// <param name="app">The OWIN pipeline.</param>
+        /// <param name="serviceProvider">A service provider for <see cref="IApplicationBuilder.ApplicationServices"/>.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/>.</returns>
         public static IApplicationBuilder UseBuilder(this AddMiddleware app, IServiceProvider serviceProvider)
         {
             if (app == null)
@@ -142,11 +167,24 @@ private static CreateMiddleware CreateMiddlewareFactory(Func<RequestDelegate, Re
             };
         }
 
+        /// <summary>
+        /// Creates an <see cref="IApplicationBuilder"/> for an OWIN pipeline.
+        /// </summary>
+        /// <param name="app">The OWIN pipeline.</param>
+        /// <param name="pipeline">A delegate used to configure a middleware pipeline.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/>.</returns>
         public static AddMiddleware UseBuilder(this AddMiddleware app, Action<IApplicationBuilder> pipeline)
         {
             return app.UseBuilder(pipeline, serviceProvider: null);
         }
 
+        /// <summary>
+        /// Creates an <see cref="IApplicationBuilder"/> for an OWIN pipeline.
+        /// </summary>
+        /// <param name="app">The OWIN pipeline.</param>
+        /// <param name="pipeline">A delegate used to configure a middleware pipeline.</param>
+        /// <param name="serviceProvider">A service provider for <see cref="IApplicationBuilder.ApplicationServices"/>.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/>.</returns>
         public static AddMiddleware UseBuilder(this AddMiddleware app, Action<IApplicationBuilder> pipeline, IServiceProvider serviceProvider)
         {
             if (app == null)

src/Http/Owin/src/OwinFeatureCollection.cs

@@ -23,6 +23,9 @@ namespace Microsoft.AspNetCore.Owin
 {
     using SendFileFunc = Func<string, long, long?, CancellationToken, Task>;
 
+    /// <summary>
+    /// OWIN feature collection.
+    /// </summary>
     public class OwinFeatureCollection :
         IFeatureCollection,
         IHttpRequestFeature,
@@ -36,10 +39,17 @@ public class OwinFeatureCollection :
         IHttpWebSocketFeature,
         IOwinEnvironmentFeature
     {
+        /// <summary>
+        /// Gets or sets OWIN environment values.
+        /// </summary>
         public IDictionary<string, object> Environment { get; set; }
         private PipeWriter _responseBodyWrapper;
         private bool _headersSent;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="OwinFeatureCollection"/>.
+        /// </summary>
+        /// <param name="environment">The environment values.</param>
         public OwinFeatureCollection(IDictionary<string, object> environment)
         {
             Environment = environment;
@@ -318,16 +328,19 @@ Task<WebSocket> IHttpWebSocketFeature.AcceptAsync(WebSocketAcceptContext context
 
         // IFeatureCollection
 
+        /// <inheritdoc/>
         public int Revision
         {
             get { return 0; } // Not modifiable
         }
 
+        /// <inheritdoc/>
         public bool IsReadOnly
         {
             get { return true; }
         }
 
+        /// <inheritdoc/>
         public object this[Type key]
         {
             get { return Get(key); }
@@ -355,6 +368,7 @@ private bool SupportsInterface(Type key)
             return false;
         }
 
+        /// <inheritdoc/>
         public object Get(Type key)
         {
             if (SupportsInterface(key))
@@ -364,16 +378,19 @@ public object Get(Type key)
             return null;
         }
 
+        /// <inheritdoc/>
         public void Set(Type key, object value)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public TFeature Get<TFeature>()
         {
             return (TFeature)this[typeof(TFeature)];
         }
 
+        /// <inheritdoc/>
         public void Set<TFeature>(TFeature instance)
         {
             this[typeof(TFeature)] = instance;
@@ -384,6 +401,7 @@ IEnumerator IEnumerable.GetEnumerator()
             return GetEnumerator();
         }
 
+        /// <inheritdoc/>
         public IEnumerator<KeyValuePair<Type, object>> GetEnumerator()
         {
             yield return new KeyValuePair<Type, object>(typeof(IHttpRequestFeature), this);
@@ -431,6 +449,7 @@ Task IHttpResponseBodyFeature.CompleteAsync()
             return Task.CompletedTask;
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
         }