documentation updates

Sources/X509/CSR/CSRAttribute.swift

@@ -27,7 +27,7 @@ extension CertificateSigningRequest {
     public struct Attribute {
         /// The identifier for this attribute type.
         ///
-        /// Common values are stored in `ASN1ObjectIdentifier.X509ExtensionID`.
+        /// Common values are stored in `ASN1ObjectIdentifier.CSRAttributes`.
         public var oid: ASN1ObjectIdentifier
 
         /// The encoded bytes of the values of this attribute.

Sources/X509/CSR/CertificateSigningRequest.swift

@@ -77,7 +77,7 @@ public struct CertificateSigningRequest {
     @usableFromInline
     let signatureBytes: ArraySlice<UInt8>
 
-    /// Construct a Certificate Signing Request from constituent parts.
+    /// Creates a certificate signing request from constituent parts.
     ///
     /// This API is generally not recommended for use, as it makes it very easy to construct a ``CertificateSigningRequest``
     /// whose ``signature`` is not valid. However, for testing and validation purposes it is useful to be
@@ -114,7 +114,7 @@ public struct CertificateSigningRequest {
         self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
     }
 
-    /// Construct a CSR for a specific private key.
+    /// Creates a CSR for a specific private key.
     ///
     /// This API can be used to construct a certificate signing request that can be passed to a certificate
     /// authority. It will correctly generate a signature over the request.
@@ -150,7 +150,7 @@ public struct CertificateSigningRequest {
         self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
     }
 
-    /// Construct a CSR for a specific private key.
+    /// Creates a CSR for a specific private key.
     ///
     /// This API can be used to construct a certificate signing request that can be passed to a certificate
     /// authority. It will correctly generate a signature over the request.
@@ -189,7 +189,7 @@ public struct CertificateSigningRequest {
         self.signatureBytes = try DER.Serializer.serialized(element: ASN1BitString(self.signature))[...]
     }
 
-    /// Construct a CSR for a specific private key.
+    /// Creates a CSR for a specific private key.
     ///
     /// This API can be used to construct a certificate signing request that can be passed to a certificate
     /// authority. It will correctly generate a signature over the request.

Sources/X509/CSR/ExtensionRequest.swift

@@ -25,7 +25,7 @@ public struct ExtensionRequest: Hashable, Sendable {
 
     /// Construct an ``ExtensionRequest`` from a given set of extensions.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - extensions: The extensions to attach to this ``ExtensionRequest``.
     @inlinable
     public init(extensions: Certificate.Extensions) {
@@ -34,7 +34,7 @@ public struct ExtensionRequest: Hashable, Sendable {
 
     /// Unwrap a ``CertificateSigningRequest/Attribute`` that contains an ``ExtensionRequest``.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - attribute: The attribute to unwrap
     /// - throws: If the attribute is ill-formed, or does not contain an ``ExtensionRequest``.
     @inlinable
@@ -60,7 +60,7 @@ public struct ExtensionRequest: Hashable, Sendable {
 extension CertificateSigningRequest.Attribute {
     /// Wrap an ``ExtensionRequest`` into a ``CertificateSigningRequest/Attribute``.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - extensionRequest: The ``ExtensionRequest`` to wrap.
     @inlinable
     public init(_ extensionRequest: ExtensionRequest) throws {

Sources/X509/Certificate.swift

@@ -60,7 +60,7 @@ import SwiftASN1
 /// Both of these goals encourage this type to be immutable. A ``Certificate`` represents
 /// a specific assertion of identity. Its ``Certificate/signature-swift.property`` is signed
 /// across the rest of the data. Allowing users to change this data makes it easy to accidentally modify
-/// a ``Certificate`` in one part of your code and not realise that the signature has inevitably
+/// a ``Certificate`` in one part of your code and not realize that the signature has inevitably
 /// been invalidated.
 #if canImport(Security)
 ///
@@ -146,14 +146,14 @@ public struct Certificate {
     /// The bytes of the ``Signature``.
     ///
     /// These are preserved to ensure that we reserialize exactly what we deserialized, regardless
-    /// of any canonicalisation we might do.
+    /// of any canonicalization we might do.
     @usableFromInline
     internal let signatureBytes: ArraySlice<UInt8>
 
     /// The bytes of the ``signatureAlgorithm-swift.property``.
     ///
     /// These are preserved to ensure that we reserialize exactly what we deserialized, regardless of
-    /// any canonicalisation we might do.
+    /// any canonicalization we might do.
     @usableFromInline
     internal let signatureAlgorithmBytes: ArraySlice<UInt8>
 

Sources/X509/CertificatePrivateKey.swift

@@ -23,14 +23,14 @@ import _CryptoExtras
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 extension Certificate {
-    /// A private key that can be used with a certificate.
+    /// A private key for use with a certificate.
     ///
-    /// This type provides an opaque wrapper around the various private key types
-    /// provided by `swift-crypto` and `Security`. Users are expected to construct this key from
+    /// This type is an opaque wrapper around the various private key types
+    /// provided by `swift-crypto` and `Security`. Construct this key from
     /// one of those types.
     ///
-    /// As private keys are never sent over the wire, this type does not offer
-    /// support for being unwrapped back into the underlying key types.
+    /// As private keys are never sent over the wire, this type does not support
+    /// unwrapping back into the underlying key types.
     public struct PrivateKey {
         @usableFromInline
         var backing: BackingPrivateKey

Sources/X509/CertificatePublicKey.swift

@@ -23,11 +23,11 @@ import Foundation
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 extension Certificate {
-    /// A public key that can be used with a certificate.
+    /// A public key for use with a certificate.
     ///
-    /// This type provides an opaque wrapper around the various public key types
-    /// provided by `swift-crypto`. Users are expected to construct this key from
-    /// one of those types, or to decode it from the network.
+    /// This type is an opaque wrapper around the various public key types
+    /// provided by `swift-crypto`. Construct this key from
+    /// one of those types, or decode it from the network.
     public struct PublicKey {
         @usableFromInline
         var backing: BackingPublicKey
@@ -311,7 +311,7 @@ extension P256.Signing.PublicKey {
     ///
     /// Fails if the key is not a P256 key.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - key: The key to unwrap.
     public init?(_ key: Certificate.PublicKey) {
         guard case .p256(let inner) = key.backing else {
@@ -327,7 +327,7 @@ extension P384.Signing.PublicKey {
     ///
     /// Fails if the key is not a P384 key.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - key: The key to unwrap.
     public init?(_ key: Certificate.PublicKey) {
         guard case .p384(let inner) = key.backing else {
@@ -343,7 +343,7 @@ extension P521.Signing.PublicKey {
     ///
     /// Fails if the key is not a P521 key.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - key: The key to unwrap.
     public init?(_ key: Certificate.PublicKey) {
         guard case .p521(let inner) = key.backing else {
@@ -359,7 +359,7 @@ extension _RSA.Signing.PublicKey {
     ///
     /// Fails if the key is not an RSA key.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - key: The key to unwrap.
     public init?(_ key: Certificate.PublicKey) {
         guard case .rsa(let inner) = key.backing else {
@@ -375,7 +375,7 @@ extension Curve25519.Signing.PublicKey {
     ///
     /// Fails if the key is not a Curve25519 key.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///     - key: The key to unwrap.
     public init?(_ key: Certificate.PublicKey) {
         guard case .ed25519(let inner) = key.backing else {

Sources/X509/CertificateSerialNumber.swift

@@ -52,7 +52,7 @@ extension Certificate {
         ///
         /// In general this API should only be used for testing, as fixed width integers
         /// are not sufficiently large for use in certificates. Using this API for production
-        /// use-cases may expose users to hash collision attacks on generated certificates.
+        /// use cases may expose users to hash collision attacks on generated certificates.
         ///
         /// Prefer using ``Certificate/SerialNumber-swift.struct/init(integerLiteral:)``
         /// with a `StaticBigInt` which enables arbitrary-precision.

Sources/X509/CryptographicMessageSyntax/CMSOperations.swift

@@ -19,6 +19,7 @@ import Foundation
 import SwiftASN1
 import Crypto
 
+/// A namespace for Cryptographic Message Syntax (CMS) operations.
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 public enum CMS: Sendable {
     @_spi(CMS)

Sources/X509/DistinguishedName.swift

@@ -20,7 +20,7 @@ import SwiftASN1
 /// distinguished names were the primary key, enabling the identification of a specific entity
 /// within the directory.
 ///
-/// These use-cases are largely obsolete, but distinguished names continue to be used to identify
+/// These use cases are largely obsolete, but distinguished names continue to be used to identify
 /// both the subject of and issuer of a given X.509 certificate. In this context, the distinguished
 /// name is a largely opaque identifier that just happens to have a human-readable string representation.
 ///

Sources/X509/DistinguishedNameBuilder/DNBuilder.swift

@@ -87,6 +87,8 @@ public struct DistinguishedNameBuilder: Sendable {
     }
 }
 
+/// A type that can be converted to a ``RelativeDistinguishedName``.
 public protocol RelativeDistinguishedNameConvertible {
+    /// Creates a ``RelativeDistinguishedName`` from this value.
     func makeRDN() throws -> RelativeDistinguishedName
 }