Add more doc comments (#28910)

* Add more doc comments

* DataProtection
* WebUtilities
* JSInterop

* Apply suggestions from code review

Co-authored-by: Chris Ross <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

Co-authored-by: Chris Ross <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

Author: 3 people

src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs

@@ -22,15 +22,19 @@ public sealed class AuthenticatedEncryptorFactory : IAuthenticatedEncryptorFacto
     {
         private readonly ILoggerFactory _loggerFactory;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="AuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public AuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _loggerFactory = loggerFactory;
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as AuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not AuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs

@@ -23,15 +23,19 @@ public sealed class CngCbcAuthenticatedEncryptorFactory : IAuthenticatedEncrypto
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public CngCbcAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<CngCbcAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as CngCbcAuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not CngCbcAuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs

@@ -23,11 +23,16 @@ public sealed class CngGcmAuthenticatedEncryptorFactory : IAuthenticatedEncrypto
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public CngGcmAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<CngGcmAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
             var descriptor = key.Descriptor as CngGcmAuthenticatedEncryptorDescriptor;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs

@@ -1,10 +1,13 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel
 {
+    /// <summary>
+    /// A factory for producing <see cref="IAuthenticatedEncryptorDescriptor"/>.
+    /// </summary>
     public abstract class AlgorithmConfiguration
     {
         internal const int KDK_SIZE_IN_BYTES = 512 / 8;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs

@@ -30,6 +30,7 @@ public sealed class AuthenticatedEncryptorConfiguration : AlgorithmConfiguration
         /// </remarks>
         public ValidationAlgorithm ValidationAlgorithm { get; set; } = ValidationAlgorithm.HMACSHA256;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs

@@ -12,6 +12,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     /// </summary>
     public sealed class AuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="AuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="AuthenticatedEncryptorDescriptor"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public AuthenticatedEncryptorDescriptor(AuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -32,6 +37,7 @@ public AuthenticatedEncryptorDescriptor(AuthenticatedEncryptorConfiguration conf
 
         internal AuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc/>
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs

@@ -73,6 +73,7 @@ public sealed class CngCbcAuthenticatedEncryptorConfiguration : AlgorithmConfigu
         [ApplyPolicy]
         public string? HashAlgorithmProvider { get; set; } = null;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs

@@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     [SupportedOSPlatform("windows")]
     public sealed class CngCbcAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="CngCbcAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public CngCbcAuthenticatedEncryptorDescriptor(CngCbcAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -34,6 +39,7 @@ public CngCbcAuthenticatedEncryptorDescriptor(CngCbcAuthenticatedEncryptorConfig
 
         internal CngCbcAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs

@@ -49,6 +49,7 @@ public sealed class CngGcmAuthenticatedEncryptorConfiguration : AlgorithmConfigu
         [ApplyPolicy]
         public int EncryptionAlgorithmKeySize { get; set; } = 256;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs

@@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     [SupportedOSPlatform("windows")]
     public sealed class CngGcmAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngGcmAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="CngCbcAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public CngGcmAuthenticatedEncryptorDescriptor(CngGcmAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -34,6 +39,7 @@ public CngGcmAuthenticatedEncryptorDescriptor(CngGcmAuthenticatedEncryptorConfig
 
         internal CngGcmAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs

@@ -49,6 +49,7 @@ public sealed class ManagedAuthenticatedEncryptorConfiguration : AlgorithmConfig
         [ApplyPolicy]
         public Type ValidationAlgorithmType { get; set; } = typeof(HMACSHA256);
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs

@@ -13,6 +13,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     /// </summary>
     public sealed class ManagedAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="ManagedAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="ManagedAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public ManagedAuthenticatedEncryptorDescriptor(ManagedAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -33,6 +38,7 @@ public ManagedAuthenticatedEncryptorDescriptor(ManagedAuthenticatedEncryptorConf
 
         internal ManagedAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs

@@ -6,6 +6,9 @@
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel
 {
+    /// <summary>
+    /// Data protection extensions for <see cref="XElement"/>.
+    /// </summary>
     public static class XmlExtensions
     {
         internal static bool IsMarkedAsRequiringEncryption(this XElement element)

src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs

@@ -6,6 +6,9 @@
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
 {
+    /// <summary>
+    /// A factory to produce <see cref="IAuthenticatedEncryptor"/> instances.
+    /// </summary>
     public interface IAuthenticatedEncryptorFactory
     {
         /// <summary>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs

@@ -19,15 +19,19 @@ public sealed class ManagedAuthenticatedEncryptorFactory : IAuthenticatedEncrypt
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="ManagedAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public ManagedAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<ManagedAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as ManagedAuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not ManagedAuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.AspNetCore.DataProtection
 {
+    /// <summary>
+    /// Data protection extensions for <see cref="IServiceProvider"/>.
+    /// </summary>
     public static class DataProtectionUtilityExtensions
     {
         /// <summary>

src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs

@@ -62,6 +62,7 @@ public EphemeralDataProtectionProvider(ILoggerFactory loggerFactory)
             _dataProtectionProvider = new KeyRingBasedDataProtectionProvider(keyringProvider, loggerFactory);
         }
 
+        /// <inheritdoc />
         public IDataProtector CreateProtector(string purpose)
         {
             if (purpose == null)

src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs

@@ -11,6 +11,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface ICacheableKeyRingProvider
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         CacheableKeyRing GetCacheableKeyRing(DateTimeOffset now);
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs

@@ -13,10 +13,22 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface IInternalXmlKeyManager
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IKey CreateNewKey(Guid keyId, DateTimeOffset creationDate, DateTimeOffset activationDate, DateTimeOffset expirationDate);
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IAuthenticatedEncryptorDescriptor DeserializeDescriptorFromKeyElement(XElement keyElement);
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         void RevokeSingleKey(Guid keyId, DateTimeOffset revocationDate, string? reason);
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs

@@ -9,6 +9,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface IKeyRingProvider
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IKeyRing GetCurrentKeyRing();
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs

@@ -20,6 +20,9 @@ public class KeyManagementOptions
         private static readonly TimeSpan _maxServerClockSkew = TimeSpan.FromMinutes(5);
         private TimeSpan _newKeyLifetime = TimeSpan.FromDays(90);
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="KeyManagementOptions"/>.
+        /// </summary>
         public KeyManagementOptions()
         {
         }

src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs

@@ -136,6 +136,7 @@ internal XmlKeyManager(
 
         internal IXmlRepository KeyRepository { get; }
 
+        /// <inheritdoc />
         public IKey CreateNewKey(DateTimeOffset activationDate, DateTimeOffset expirationDate)
         {
             return _internalKeyManager.CreateNewKey(
@@ -151,6 +152,7 @@ private static string DateTimeOffsetToFilenameSafeString(DateTimeOffset dateTime
             return dateTime.UtcDateTime.ToString("yyyyMMddTHHmmssFFFFFFFZ", CultureInfo.InvariantCulture);
         }
 
+        /// <inheritdoc/>
         public IReadOnlyCollection<IKey> GetAllKeys()
         {
             var allElements = KeyRepository.GetAllElements();
@@ -245,6 +247,7 @@ public IReadOnlyCollection<IKey> GetAllKeys()
             return keyIdToKeyMap.Values.ToList().AsReadOnly();
         }
 
+        /// <inheritdoc/>
         public CancellationToken GetCacheExpirationToken()
         {
             Debug.Assert(_cacheExpirationTokenSource != null, $"{nameof(TriggerAndResetCacheExpirationToken)} must have been called first.");
@@ -316,6 +319,7 @@ private object ProcessRevocationElement(XElement revocationElement)
             }
         }
 
+        /// <inheritdoc/>
         public void RevokeAllKeys(DateTimeOffset revocationDate, string? reason = null)
         {
             // <revocation version="1">
@@ -341,6 +345,7 @@ public void RevokeAllKeys(DateTimeOffset revocationDate, string? reason = null)
             TriggerAndResetCacheExpirationToken();
         }
 
+        /// <inheritdoc/>
         public void RevokeKey(Guid keyId, string? reason = null)
         {
             _internalKeyManager.RevokeSingleKey(

src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj

@@ -1,11 +1,10 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core logic to protect and unprotect data, similar to DPAPI.</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework)</TargetFrameworks>
     <TargetFrameworks Condition="'$(DotNetBuildFromSource)' == 'true'">$(DefaultNetCoreTargetFramework)</TargetFrameworks>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;dataprotection</PackageTags>

src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs

@@ -62,6 +62,7 @@ public FileSystemXmlRepository(DirectoryInfo directory, ILoggerFactory loggerFac
         /// </summary>
         public DirectoryInfo Directory { get; }
 
+        /// <inheritdoc/>
         public virtual IReadOnlyCollection<XElement> GetAllElements()
         {
             // forces complete enumeration
@@ -105,6 +106,7 @@ private XElement ReadElementFromFile(string fullPath)
             }
         }
 
+        /// <inheritdoc/>
         public virtual void StoreElement(XElement element, string friendlyName)
         {
             if (element == null)

src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs

@@ -54,6 +54,7 @@ public RegistryXmlRepository(RegistryKey registryKey, ILoggerFactory loggerFacto
         /// </summary>
         public RegistryKey RegistryKey { get; }
 
+        /// <inheritdoc/>
         public virtual IReadOnlyCollection<XElement> GetAllElements()
         {
             // forces complete enumeration
@@ -133,6 +134,7 @@ private static bool IsSafeRegistryValueName(string filename)
             return (!string.IsNullOrEmpty(data)) ? XElement.Parse(data) : null;
         }
 
+        /// <inheritdoc/>
         public virtual void StoreElement(XElement element, string friendlyName)
         {
             if (element == null)