docs: add XML documentation for CMS attribute and originator generators (Batch 16d)

crypto/src/cms/CMSCompressedDataGenerator.cs

@@ -7,14 +7,19 @@
 
 namespace Org.BouncyCastle.Cms
 {
-    /// <summary>General class for generating a compressed CMS message.</summary>
+    /// <summary>
+    /// Generator for CMS CompressedData messages. Compresses content with ZLIB and returns a
+    /// <see cref="CmsCompressedData"/> instance (read-side: Batch 15d, #703).
+    /// </summary>
     public class CmsCompressedDataGenerator
     {
+        /// <summary>The object identifier for ZLIB compression (<c>id-zlibCompress</c>).</summary>
         public static readonly string ZLib = CmsObjectIdentifiers.ZlibCompress.Id;
 
         private static readonly AlgorithmIdentifier ZLibCompressionAlgorithm =
             new AlgorithmIdentifier(CmsObjectIdentifiers.ZlibCompress);
 
+        /// <summary>Creates a compressed-data generator.</summary>
         public CmsCompressedDataGenerator()
         {
         }
@@ -24,6 +29,14 @@ public CmsCompressedDataGenerator()
         public CmsCompressedData Generate(CmsProcessable content, string compressionOid) =>
             Generate(CmsUtilities.GetTypedData(content), compressionOid);
 
+        /// <summary>Generates a CMS CompressedData message for <paramref name="content"/>.</summary>
+        /// <param name="content">The content to compress.</param>
+        /// <param name="compressionOid">The compression algorithm OID (currently only <see cref="ZLib"/>).</param>
+        /// <returns>A compressed-data structure.</returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown if <paramref name="compressionOid"/> is not supported.
+        /// </exception>
+        /// <exception cref="CmsException">Thrown if the content cannot be compressed.</exception>
         public CmsCompressedData Generate(CmsTypedData content, string compressionOid)
         {
             if (ZLib != compressionOid)

crypto/src/cms/DefaultAuthenticatedAttributeTableGenerator.cs

@@ -7,7 +7,11 @@
 
 namespace Org.BouncyCastle.Cms
 {
-    /// <summary>Default authenticated attributes generator.</summary>
+    /// <summary>
+    /// Default authenticated-attribute generator for CMS AuthenticatedData. Supplies contentType, messageDigest, and
+    /// cmsAlgorithmProtect unless overridden. Used by <see cref="CmsAuthenticatedDataGenerator"/> and related
+    /// generators.
+    /// </summary>
     public class DefaultAuthenticatedAttributeTableGenerator
         : CmsAttributeTableGenerator
     {
@@ -33,6 +37,8 @@ public DefaultAuthenticatedAttributeTableGenerator(AttributeTable attributeTable
         }
 
         /// <summary>Returns a populated <see cref="AttributeTable"/>.</summary>
+        /// <param name="parameters">Generation parameters supplied by the CMS generator.</param>
+        /// <returns>An attribute table including standard authenticated attributes.</returns>
         public virtual AttributeTable GetAttributes(IDictionary<CmsAttributeTableParameter, object> parameters)
         {
             var table = CreateStandardAttributeTable(parameters);

crypto/src/cms/DefaultSignedAttributeTableGenerator.cs

@@ -8,7 +8,11 @@
 
 namespace Org.BouncyCastle.Cms
 {
-    /// <summary>Default signed attributes generator.</summary>
+    /// <summary>
+    /// Default signed-attribute generator for CMS SignedData. Supplies contentType, signingTime, messageDigest, and
+    /// cmsAlgorithmProtect unless overridden. Used by <see cref="SignerInfoGeneratorBuilder"/> and
+    /// <see cref="CmsSignedDataGenerator"/> <c>AddSigner</c> overloads.
+    /// </summary>
     public class DefaultSignedAttributeTableGenerator
         : CmsAttributeTableGenerator
     {
@@ -33,7 +37,9 @@ public DefaultSignedAttributeTableGenerator(AttributeTable attributeTable)
             }
         }
 
-        /// <summary>Returns a populated <see cref=" AttributeTable"/>.</summary>
+        /// <summary>Returns a populated <see cref="AttributeTable"/>.</summary>
+        /// <param name="parameters">Generation parameters supplied by the CMS generator.</param>
+        /// <returns>An attribute table including standard signed attributes.</returns>
         public virtual AttributeTable GetAttributes(IDictionary<CmsAttributeTableParameter, object> parameters)
         {
             var table = CreateStandardAttributeTable(parameters);

crypto/src/cms/OriginatorInfoGenerator.cs

@@ -7,27 +7,45 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>
+    /// Builds CMS <c>OriginatorInfo</c> values carrying certificates and revocation information for authenticated
+    /// messages. The read-side wrapper is <see cref="OriginatorInformation"/>.
+    /// </summary>
     public class OriginatorInfoGenerator
     {
         private readonly List<Asn1Encodable> origCerts;
         private readonly List<Asn1Encodable> origCrls;
 
+        /// <summary>Creates a generator containing a single originator certificate.</summary>
+        /// <param name="origCert">The originator's X.509 certificate.</param>
         public OriginatorInfoGenerator(X509Certificate origCert)
         {
             this.origCerts = new List<Asn1Encodable>{ origCert.CertificateStructure };
             this.origCrls = null;
         }
 
+        /// <summary>Creates a generator from a store of originator certificates.</summary>
+        /// <param name="x509Certs">Public-key certificates to include, or null to omit.</param>
         public OriginatorInfoGenerator(IStore<X509Certificate> x509Certs)
             : this(x509Certs, null, null, null)
         {
         }
 
+        /// <summary>Creates a generator from certificate and CRL stores.</summary>
+        /// <param name="x509Certs">Public-key certificates to include, or null to omit.</param>
+        /// <param name="x509Crls">CRLs to include, or null to omit.</param>
         public OriginatorInfoGenerator(IStore<X509Certificate> x509Certs, IStore<X509Crl> x509Crls)
             : this(x509Certs, x509Crls, null, null)
         {
         }
 
+        /// <summary>
+        /// Creates a generator from certificate, CRL, attribute-certificate, and other-revocation stores.
+        /// </summary>
+        /// <param name="x509Certs">Public-key certificates to include, or null to omit.</param>
+        /// <param name="x509Crls">CRLs to include, or null to omit.</param>
+        /// <param name="x509AttrCerts">Attribute certificates to include, or null to omit.</param>
+        /// <param name="otherRevocationInfos">Other revocation information to include, or null to omit.</param>
         public OriginatorInfoGenerator(IStore<X509Certificate> x509Certs, IStore<X509Crl> x509Crls,
             IStore<X509V2AttributeCertificate> x509AttrCerts, IStore<OtherRevocationInfoFormat> otherRevocationInfos)
         {
@@ -63,6 +81,8 @@ public OriginatorInfoGenerator(IStore<X509Certificate> x509Certs, IStore<X509Crl
             this.origCrls = revocations;
         }
 
+        /// <summary>Builds an OriginatorInfo structure from the configured stores.</summary>
+        /// <returns>A CMS OriginatorInfo value.</returns>
         public virtual OriginatorInfo Generate() => new OriginatorInfo(origCerts?.ToDerSet(), origCrls?.ToDerSet());
     }
 }

crypto/src/cms/SimpleAttributeTableGenerator.cs

@@ -5,23 +5,27 @@
 
 namespace Org.BouncyCastle.Cms
 {
-	/**
-	 * Basic generator that just returns a preconstructed attribute table
-	 */
-	public class SimpleAttributeTableGenerator
-		: CmsAttributeTableGenerator
-	{
-		private readonly AttributeTable attributes;
+    /// <summary>
+    /// Returns a fixed <see cref="AttributeTable"/> regardless of generation parameters. Used for unsigned attributes
+    /// and other cases where attributes are fully preconfigured.
+    /// </summary>
+    public class SimpleAttributeTableGenerator
+        : CmsAttributeTableGenerator
+    {
+        private readonly AttributeTable attributes;
 
-		public SimpleAttributeTableGenerator(
-			AttributeTable attributes)
-		{
-			this.attributes = attributes;
-		}
+        /// <summary>Creates a generator that always returns <paramref name="attributes"/>.</summary>
+        /// <param name="attributes">The attribute table to return from <see cref="GetAttributes"/>.</param>
+        public SimpleAttributeTableGenerator(
+            AttributeTable attributes)
+        {
+            this.attributes = attributes;
+        }
 
-		public virtual AttributeTable GetAttributes(IDictionary<CmsAttributeTableParameter, object> parameters)
-		{
-			return attributes;
-		}
-	}
+        /// <inheritdoc/>
+        public virtual AttributeTable GetAttributes(IDictionary<CmsAttributeTableParameter, object> parameters)
+        {
+            return attributes;
+        }
+    }
 }