Add XML documentation to all public types and members

Author: andrei-m-code

CorePush/Apple/ApnPushType.cs

@@ -1,8 +1,24 @@
 namespace CorePush.Apple;
 
+/// <summary>
+/// The type of APNs push notification. Required for iOS 13+.
+/// See <see href="https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns">Apple documentation</see>.
+/// </summary>
 public enum ApnPushType
 {
+    /// <summary>
+    /// Background notification that wakes the app to perform a task.
+    /// Must set apns-priority to 5.
+    /// </summary>
     Background,
+
+    /// <summary>
+    /// Visible notification that displays an alert, plays a sound, or badges the app icon.
+    /// </summary>
     Alert,
+
+    /// <summary>
+    /// VoIP push notification. Requires the VoIP push entitlement in your app.
+    /// </summary>
     Voip
-}
+}

CorePush/Apple/ApnSender.cs

@@ -38,7 +38,11 @@ public class ApnSender : IApnSender
     private readonly HttpClient http;
     private readonly IJsonSerializer serializer;
 
-    /// <param name="http">A <see cref="HttpClient"/> dedicated to this <see cref="ApnSender"/>. Do not use a shared <see cref="HttpClient"/> instance, since its instance-level state may be modified. However, its <see cref="HttpClientHandler" can be shared.</param>
+    /// <summary>
+    /// Creates a new Apple Push Notification sender with default JSON serialization.
+    /// </summary>
+    /// <param name="settings">Apple Push Notification settings (team ID, key, bundle ID, etc.).</param>
+    /// <param name="http">A <see cref="HttpClient"/> dedicated to this <see cref="ApnSender"/>. Do not use a shared <see cref="HttpClient"/> instance, since its instance-level state may be modified. However, its <see cref="HttpClientHandler"/> can be shared.</param>
     public ApnSender(ApnSettings settings, HttpClient http) : this(settings, http, new DefaultCorePushJsonSerializer())
     {
     }

CorePush/Apple/ApnServerType.cs

@@ -1,7 +1,19 @@
-namespace CorePush.Apple;
+namespace CorePush.Apple;
 
+/// <summary>
+/// Specifies the APNs server environment to send push notifications to.
+/// </summary>
 public enum ApnServerType
 {
+    /// <summary>
+    /// Apple sandbox environment for development and testing.
+    /// Uses api.development.push.apple.com.
+    /// </summary>
     Development,
+
+    /// <summary>
+    /// Apple production environment for live apps.
+    /// Uses api.push.apple.com.
+    /// </summary>
     Production
-}
+}

CorePush/Apple/ApnSettings.cs

@@ -1,29 +1,38 @@
 namespace CorePush.Apple;
 
+/// <summary>
+/// Configuration settings for Apple Push Notification service (APNs).
+/// Uses token-based authentication with a .p8 key file from the Apple Developer portal.
+/// </summary>
 public class ApnSettings
 {
     /// <summary>
-    /// p8 certificate string
+    /// The contents of the .p8 private key file downloaded from the Apple Developer portal.
+    /// Can include or omit the PEM header/footer lines.
     /// </summary>
     public string P8PrivateKey { get; set; }
 
     /// <summary>
-    /// 10 digit p8 certificate id. Usually a part of a downloadable certificate filename
+    /// The 10-character Key ID for the .p8 key, found in the Apple Developer portal
+    /// or as part of the downloaded .p8 filename.
     /// </summary>
-    public string P8PrivateKeyId { get; set; } 
+    public string P8PrivateKeyId { get; set; }
 
     /// <summary>
-    /// Apple 10 digit team id
+    /// Your 10-character Apple Developer Team ID, visible in the Apple Developer portal
+    /// under Membership details.
     /// </summary>
     public string TeamId { get; set; }
 
     /// <summary>
-    /// App slug / bundle name
+    /// The bundle identifier of your app (e.g. "com.example.myapp"),
+    /// used as the apns-topic header value.
     /// </summary>
     public string AppBundleIdentifier { get; set; }
 
     /// <summary>
-    /// Development or Production server
+    /// The APNs server environment: <see cref="ApnServerType.Development"/> for sandbox
+    /// or <see cref="ApnServerType.Production"/> for live apps.
     /// </summary>
     public ApnServerType ServerType { get; set; }
-}
+}

CorePush/Apple/ApnsResponse.cs

@@ -1,52 +1,126 @@
-namespace CorePush.Apple;
+namespace CorePush.Apple;
 
+/// <summary>
+/// Represents the response from the Apple Push Notification service.
+/// </summary>
 public class ApnsResponse
 {
+    /// <summary>
+    /// Indicates whether the push notification was accepted by APNs.
+    /// </summary>
     public bool IsSuccess { get; set;  }
 
+    /// <summary>
+    /// Error details returned by APNs when the notification was rejected. Null on success.
+    /// </summary>
     public ApnsError Error { get; set; }
 }
 
+/// <summary>
+/// Error information returned by APNs when a push notification is rejected.
+/// </summary>
 public class ApnsError
 {
     /// <summary>
-    /// Use <see cref="ApnsErrorReasons"/> to compare against
+    /// The error reason string returned by APNs.
+    /// Compare against constants in <see cref="ApnsErrorReasons"/>.
     /// </summary>
     public string Reason {get; set;}
+
+    /// <summary>
+    /// For <see cref="ApnsErrorReasons.Unregistered"/> errors, the last time APNs confirmed
+    /// the device token was valid, as a UNIX epoch timestamp in milliseconds.
+    /// </summary>
     public long? Timestamp {get; set; }
 }
 
 /// <summary>
-/// https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW15
+/// Constants for all APNs error reason strings.
+/// See <see href="https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns">Apple documentation</see>.
 /// </summary>
 public static class ApnsErrorReasons
 {
+    /// <summary>The collapse identifier exceeds the maximum allowed size.</summary>
     public const string BadCollapseId = "BadCollapseId";
+
+    /// <summary>The specified device token is invalid (e.g. wrong size or contains invalid characters).</summary>
     public const string BadDeviceToken = "BadDeviceToken";
+
+    /// <summary>The apns-expiration value is invalid.</summary>
     public const string BadExpirationDate = "BadExpirationDate";
+
+    /// <summary>The apns-id value is invalid.</summary>
     public const string BadMessageId = "BadMessageId";
+
+    /// <summary>The apns-priority value is invalid.</summary>
     public const string BadPriority = "BadPriority";
+
+    /// <summary>The apns-topic value is invalid.</summary>
     public const string BadTopic = "BadTopic";
+
+    /// <summary>The device token doesn't match the specified topic.</summary>
     public const string DeviceTokenNotForTopic = "DeviceTokenNotForTopic";
+
+    /// <summary>One or more headers are repeated.</summary>
     public const string DuplicateHeaders = "DuplicateHeaders";
+
+    /// <summary>Idle timeout.</summary>
     public const string IdleTimeout = "IdleTimeout";
+
+    /// <summary>The device token was not specified in the request path.</summary>
     public const string MissingDeviceToken = "MissingDeviceToken";
+
+    /// <summary>The apns-topic header is required when the client is connected using a certificate that supports multiple topics.</summary>
     public const string MissingTopic = "MissingTopic";
+
+    /// <summary>The notification payload is empty.</summary>
     public const string PayloadEmpty = "PayloadEmpty";
+
+    /// <summary>Pushing to this topic is not allowed.</summary>
     public const string TopicDisallowed = "TopicDisallowed";
+
+    /// <summary>The certificate is invalid.</summary>
     public const string BadCertificate = "BadCertificate";
+
+    /// <summary>The client certificate doesn't match the target environment (sandbox vs. production).</summary>
     public const string BadCertificateEnvironment = "BadCertificateEnvironment";
+
+    /// <summary>The provider token is stale and a new token should be generated.</summary>
     public const string ExpiredProviderToken = "ExpiredProviderToken";
+
+    /// <summary>The specified action is not allowed.</summary>
     public const string Forbidden = "Forbidden";
+
+    /// <summary>The provider token is not valid, or the token signature could not be verified.</summary>
     public const string InvalidProviderToken = "InvalidProviderToken";
+
+    /// <summary>No provider certificate was used to connect to APNs, and the authorization header is missing or no provider token is specified.</summary>
     public const string MissingProviderToken = "MissingProviderToken";
+
+    /// <summary>The request contained an invalid path.</summary>
     public const string BadPath = "BadPath";
+
+    /// <summary>The specified HTTP method is not allowed. Use POST.</summary>
     public const string MethodNotAllowed = "MethodNotAllowed";
+
+    /// <summary>The device token is inactive for the specified topic. The <see cref="ApnsError.Timestamp"/> field contains the last valid timestamp.</summary>
     public const string Unregistered = "Unregistered";
+
+    /// <summary>The notification payload is too large (max 4096 bytes).</summary>
     public const string PayloadTooLarge = "PayloadTooLarge";
+
+    /// <summary>The provider has made too many token update requests in too short a time.</summary>
     public const string TooManyProviderTokenUpdates = "TooManyProviderTokenUpdates";
+
+    /// <summary>Too many requests were sent to APNs. Retry with exponential back-off.</summary>
     public const string TooManyRequests = "TooManyRequests";
+
+    /// <summary>An internal server error occurred on the APNs side.</summary>
     public const string InternalServerError = "InternalServerError";
+
+    /// <summary>The APNs service is unavailable. Retry later.</summary>
     public const string ServiceUnavailable = "ServiceUnavailable";
-    public const string Shutdown = "Shutdown";  
-}
+
+    /// <summary>The APNs server is shutting down.</summary>
+    public const string Shutdown = "Shutdown";
+}

CorePush/Firebase/FirebaseError.cs

@@ -1,15 +1,44 @@
-namespace CorePush.Firebase;
+namespace CorePush.Firebase;
 
+/// <summary>
+/// Error information returned by the Firebase Cloud Messaging HTTP v1 API.
+/// </summary>
 public class FirebaseError
 {
+    /// <summary>
+    /// Additional details about the error, such as the FCM-specific error code.
+    /// </summary>
     public class Detail
     {
+        /// <summary>
+        /// The protobuf "@type" URL describing this detail entry.
+        /// </summary>
         public string Type { get; set; }
+
+        /// <summary>
+        /// The FCM-specific error code (e.g. "UNREGISTERED", "INVALID_ARGUMENT").
+        /// See <see href="https://firebase.google.com/docs/cloud-messaging/send-message#rest">FCM error codes</see>.
+        /// </summary>
         public string ErrorCode { get; set; }
     }
 
+    /// <summary>
+    /// The HTTP status code returned by FCM.
+    /// </summary>
     public int Code { get; set; }
+
+    /// <summary>
+    /// A human-readable error message describing what went wrong.
+    /// </summary>
     public string Message { get; set; }
+
+    /// <summary>
+    /// The gRPC status string (e.g. "INVALID_ARGUMENT", "NOT_FOUND", "PERMISSION_DENIED").
+    /// </summary>
     public string Status { get; set; }
+
+    /// <summary>
+    /// An array of additional error detail objects with FCM-specific error codes.
+    /// </summary>
     public Detail[] Details { get; set; }
 }

CorePush/Firebase/FirebaseResponse.cs

@@ -1,7 +1,18 @@
-namespace CorePush.Firebase;
+namespace CorePush.Firebase;
 
+/// <summary>
+/// Represents the response from the Firebase Cloud Messaging HTTP v1 API.
+/// </summary>
 public class FirebaseResponse
 {
+    /// <summary>
+    /// The identifier of the sent message in the format "projects/*/messages/{message_id}".
+    /// Populated on success; null on failure.
+    /// </summary>
     public string Name { get; set; }
+
+    /// <summary>
+    /// Error details returned by FCM when the request fails. Null on success.
+    /// </summary>
     public FirebaseError Error { get; set; }
-}
+}

CorePush/Firebase/FirebaseSettings.cs

@@ -2,9 +2,18 @@
 
 namespace CorePush.Firebase;
 
+/// <summary>
+/// Configuration settings for Firebase Cloud Messaging (FCM) HTTP v1 API.
+/// This record maps directly to the Google Service Account JSON key file
+/// (e.g. myproject-12345-abc123123.json) downloaded from the Firebase Console.
+/// </summary>
+/// <param name="ProjectId">The Firebase/GCP project ID (e.g. "myproject-12345").</param>
+/// <param name="PrivateKey">The PEM-encoded RSA private key from the service account key file.</param>
+/// <param name="ClientEmail">The service account email address (e.g. "firebase-adminsdk-xxxxx@myproject.iam.gserviceaccount.com").</param>
+/// <param name="TokenUri">The OAuth 2.0 token endpoint URL, typically "https://oauth2.googleapis.com/token".</param>
 public record FirebaseSettings(
     [property: JsonPropertyName("project_id")] string ProjectId,
     [property: JsonPropertyName("private_key")] string PrivateKey,
     [property: JsonPropertyName("client_email")] string ClientEmail,
     [property: JsonPropertyName("token_uri")] string TokenUri
-);
+);

CorePush/Interfaces/IApnSender.cs

@@ -6,8 +6,23 @@
 
 namespace CorePush.Interfaces;
 
+/// <summary>
+/// Interface for sending Apple Push Notifications via the APNs HTTP/2 API.
+/// </summary>
 public interface IApnSender
 {
+    /// <summary>
+    /// Sends a push notification to an Apple device.
+    /// </summary>
+    /// <param name="notification">The notification payload object. Will be serialized to JSON.
+    /// See <see href="https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification">Apple payload documentation</see>.</param>
+    /// <param name="deviceToken">The target device token (hex string) obtained from the device at registration.</param>
+    /// <param name="apnsId">Optional unique notification identifier. APNs returns this in its response. If omitted, APNs generates a new UUID.</param>
+    /// <param name="apnsExpiration">The UNIX epoch timestamp (seconds) when the notification expires. 0 means immediate delivery only.</param>
+    /// <param name="apnsPriority">The notification priority: 10 for immediate delivery, 5 for power-saving delivery.</param>
+    /// <param name="apnPushType">The push notification type. Required for iOS 13+ and watchOS 6+.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A <see cref="PushResult"/> indicating success or failure with status code and error details.</returns>
     Task<PushResult> SendAsync(
         object notification,
         string deviceToken,
@@ -16,4 +31,4 @@ Task<PushResult> SendAsync(
         int apnsPriority = 10,
         ApnPushType apnPushType = ApnPushType.Alert,
         CancellationToken cancellationToken = default);
-}
+}

CorePush/Interfaces/IFirebaseSender.cs

@@ -1,12 +1,21 @@
 using System.Threading;
 using System.Threading.Tasks;
 
-using CorePush.Firebase;
 using CorePush.Models;
 
 namespace CorePush.Interfaces;
 
+/// <summary>
+/// Interface for sending push notifications via Firebase Cloud Messaging (FCM) HTTP v1 API.
+/// </summary>
 public interface IFirebaseSender
 {
+    /// <summary>
+    /// Sends a push notification through Firebase Cloud Messaging.
+    /// </summary>
+    /// <param name="payload">The FCM message payload object. Will be serialized to JSON.
+    /// See <see href="https://firebase.google.com/docs/cloud-messaging/send-message">FCM message format</see>.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A <see cref="PushResult"/> indicating success or failure with status code and error details.</returns>
     Task<PushResult> SendAsync(object payload, CancellationToken cancellationToken = default);
-}
+}