Added code comments

Author: leastprivilege

src/IdentityModel.AspNetCore.OAuth2Introspection/IdentityModel.AspNetCore.OAuth2Introspection.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <Description>ASP.NET Core 2.0 Middleware for validating tokens using OAuth 2.0 introspection</Description>
-    <VersionPrefix>3.0.0</VersionPrefix>
+    <VersionPrefix>3.0.1</VersionPrefix>
     <!--<VersionSuffix>rc2</VersionSuffix>-->
     <Authors>Dominick Baier;Brock Allen</Authors>
     <TargetFrameworks>netstandard2.0</TargetFrameworks>
@@ -15,6 +15,14 @@
     <RepositoryUrl>git://github.com/identitymodel/identitymodel.aspnetcore.oauth2introspection</RepositoryUrl>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|netstandard2.0|AnyCPU'">
+    <DocumentationFile>bin\Release\netstandard2.0\IdentityModel.AspNetCore.OAuth2Introspection.xml</DocumentationFile>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|netstandard2.0|AnyCPU'">
+    <DocumentationFile>bin\Debug\netstandard2.0\IdentityModel.AspNetCore.OAuth2Introspection.xml</DocumentationFile>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="SourceLink.Embed.AllSourceFiles" Version="2.4.0" PrivateAssets="all" />
     <PackageReference Include="Microsoft.AspNetCore.Authentication" Version="2.0.0" />

src/IdentityModel.AspNetCore.OAuth2Introspection/Infrastructure/AsyncLazy.cs

@@ -6,10 +6,10 @@
 
 namespace IdentityModel.AspNetCore.OAuth2Introspection.Infrastructure
 {
-    public class AsyncLazy<T> : Lazy<Task<T>>
+    internal class AsyncLazy<T> : Lazy<Task<T>>
     {
         public AsyncLazy(Func<Task<T>> taskFactory) :
             base(() => Task.Factory.StartNew(taskFactory).Unwrap())
         { }
     }
-}
+}

src/IdentityModel.AspNetCore.OAuth2Introspection/Infrastructure/TokenRetrieval.cs

@@ -7,8 +7,16 @@
 
 namespace IdentityModel.AspNetCore.OAuth2Introspection
 {
+    /// <summary>
+    /// Defines some common token retrieval strategies
+    /// </summary>
     public static class TokenRetrieval
     {
+        /// <summary>
+        /// Reads the token from the authrorization header.
+        /// </summary>
+        /// <param name="scheme">The scheme (defaults to Bearer).</param>
+        /// <returns></returns>
         public static Func<HttpRequest, string> FromAuthorizationHeader(string scheme = "Bearer")
         {
             return (request) =>
@@ -29,6 +37,11 @@ public static Func<HttpRequest, string> FromAuthorizationHeader(string scheme =
             };
         }
 
+        /// <summary>
+        /// Reads the token from a query string parameter.
+        /// </summary>
+        /// <param name="name">The name (defaults to access_token).</param>
+        /// <returns></returns>
         public static Func<HttpRequest, string> FromQueryString(string name = "access_token")
         {
             return (request) => request.Query[name].FirstOrDefault();

src/IdentityModel.AspNetCore.OAuth2Introspection/OAuth2IntrospectionDefaults.cs

@@ -3,8 +3,17 @@
 
 namespace IdentityModel.AspNetCore.OAuth2Introspection
 {
+    /// <summary>
+    /// Defaults for OAuth 2.0 introspection authentication
+    /// </summary>
     public class OAuth2IntrospectionDefaults
     {
+        /// <summary>
+        /// Gets the default authentication scheme.
+        /// </summary>
+        /// <value>
+        /// The authentication scheme.
+        /// </value>
         public static string AuthenticationScheme => "Bearer";
     }
 }

src/IdentityModel.AspNetCore.OAuth2Introspection/OAuth2IntrospectionExtensions.cs

@@ -10,17 +10,45 @@
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extensions for registering the OAuth 2.0 introspection authentication handler
+    /// </summary>
     public static class OAuth2IntrospectionExtensions
     {
+        /// <summary>
+        /// Adds the OAuth 2.0 introspection handler.
+        /// </summary>
+        /// <param name="builder">The builder.</param>
+        /// <returns></returns>
         public static AuthenticationBuilder AddOAuth2Introspection(this AuthenticationBuilder builder) 
             => builder.AddOAuth2Introspection(OAuth2IntrospectionDefaults.AuthenticationScheme);
 
+        /// <summary>
+        /// Adds the OAuth 2.0 introspection handler.
+        /// </summary>
+        /// <param name="builder">The builder.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <returns></returns>
         public static AuthenticationBuilder AddOAuth2Introspection(this AuthenticationBuilder builder, string authenticationScheme) 
             => builder.AddOAuth2Introspection(authenticationScheme, configureOptions: null);
 
+        /// <summary>
+        /// Adds the OAuth 2.0 introspection handler.
+        /// </summary>
+        /// <param name="services">The services.</param>
+        /// <param name="configureOptions">The configure options.</param>
+        /// <returns></returns>
         public static AuthenticationBuilder AddOAuth2Introspection(this AuthenticationBuilder services, Action<OAuth2IntrospectionOptions> configureOptions) 
             => services.AddOAuth2Introspection(OAuth2IntrospectionDefaults.AuthenticationScheme, configureOptions: configureOptions);
 
+
+        /// <summary>
+        /// Adds the OAuth 2.0 introspection handler.
+        /// </summary>
+        /// <param name="builder">The builder.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="configureOptions">The configure options.</param>
+        /// <returns></returns>
         public static AuthenticationBuilder AddOAuth2Introspection(this AuthenticationBuilder builder, string authenticationScheme, Action<OAuth2IntrospectionOptions> configureOptions)
         {
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<OAuth2IntrospectionOptions>, PostConfigureOAuth2IntrospectionOptions>());

src/IdentityModel.AspNetCore.OAuth2Introspection/OAuth2IntrospectionHandler.cs

@@ -16,11 +16,22 @@
 
 namespace IdentityModel.AspNetCore.OAuth2Introspection
 {
+    /// <summary>
+    /// Authentication handler for OAuth 2.0 introspection
+    /// </summary>
     public class OAuth2IntrospectionHandler : AuthenticationHandler<OAuth2IntrospectionOptions>
     {
         private readonly IDistributedCache _cache;
         private readonly ILogger<OAuth2IntrospectionHandler> _logger;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OAuth2IntrospectionHandler"/> class.
+        /// </summary>
+        /// <param name="options">The options.</param>
+        /// <param name="urlEncoder">The URL encoder.</param>
+        /// <param name="clock">The clock.</param>
+        /// <param name="loggerFactory">The logger factory.</param>
+        /// <param name="cache">The cache.</param>
         public OAuth2IntrospectionHandler(
             IOptionsMonitor<OAuth2IntrospectionOptions> options,
             UrlEncoder urlEncoder,
@@ -33,6 +44,10 @@ public OAuth2IntrospectionHandler(
             _cache = cache;
         }
 
+        /// <summary>
+        /// Tries to authenticate a reference token on the current request
+        /// </summary>
+        /// <returns></returns>
         protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
         {
             string token = Options.TokenRetriever(Context.Request);

src/IdentityModel.AspNetCore.OAuth2Introspection/OAuth2IntrospectionOptions.cs

@@ -102,6 +102,15 @@ public class OAuth2IntrospectionOptions : AuthenticationSchemeOptions
         internal AsyncLazy<IntrospectionClient> IntrospectionClient { get; set; }
         internal ConcurrentDictionary<string, AsyncLazy<IntrospectionResponse>> LazyIntrospections { get; set; }
 
+        /// <summary>
+        /// Check that the options are valid. Should throw an exception if things are not ok.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">
+        /// You must either set Authority or IntrospectionEndpoint
+        /// or
+        /// You must either set a ClientId or set an introspection HTTP handler
+        /// </exception>
+        /// <exception cref="ArgumentException">TokenRetriever must be set - TokenRetriever</exception>
         public override void Validate()
         {
             base.Validate();

src/IdentityModel.AspNetCore.OAuth2Introspection/PostConfigureOAuth2IntrospectionOptions.cs

@@ -12,7 +12,7 @@
 
 namespace IdentityModel.AspNetCore.OAuth2Introspection
 {
-    public class PostConfigureOAuth2IntrospectionOptions : IPostConfigureOptions<OAuth2IntrospectionOptions>
+    internal class PostConfigureOAuth2IntrospectionOptions : IPostConfigureOptions<OAuth2IntrospectionOptions>
     {
         private readonly IDistributedCache _cache;