Add more doc comments (#28910)

* Add more doc comments

* DataProtection
* WebUtilities
* JSInterop

* Apply suggestions from code review

Co-authored-by: Chris Ross <Tratcher@Outlook.com>
Co-authored-by: James Newton-King <james@newtonking.com>

Co-authored-by: Chris Ross <Tratcher@Outlook.com>
Co-authored-by: James Newton-King <james@newtonking.com>

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>