From 9725e2fd64ccecf2580a63dad45d573f661c2660 Mon Sep 17 00:00:00 2001
From: Hisham Bin Ateya <hishamco_2007@yahoo.com>
Date: Tue, 3 Oct 2023 18:21:39 +0300
Subject: [PATCH] Add OC.Notifications.Abstractions docs

---
 .../INotificationEvents.cs                    | 34 +++++++++++++++++++
 .../INotificationMessage.cs                   | 15 ++++++++
 .../INotificationMethodProvider.cs            | 12 ++++---
 .../INotificationMethodProviderAccessor.cs    |  8 +++++
 .../INotificationService.cs                   |  7 ++--
 .../Notification.cs                           | 11 +++---
 .../NotificationContext.cs                    | 30 ++++++++++++----
 7 files changed, 101 insertions(+), 16 deletions(-)

diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationEvents.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationEvents.cs
index 3636d9028bc..1d992febec2 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationEvents.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationEvents.cs
@@ -2,19 +2,53 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a contract for notification events.
+/// </summary>
 public interface INotificationEvents
 {
+    /// <summary>
+    /// Occurs before the notification is created.
+    /// </summary>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task CreatingAsync(NotificationContext context);
 
+    /// <summary>
+    /// Occurs after the notification is created.
+    /// </summary>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task CreatedAsync(NotificationContext context);
 
+    /// <summary>
+    /// Occurs before the notification is sent.
+    /// </summary>
+    /// <param name="provider">The <see cref="INotificationMethodProvider"/>.</param>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task SendingAsync(INotificationMethodProvider provider, NotificationContext context);
 
+    /// <summary>
+    /// Occurs after the notification is sent.
+    /// </summary>
+    /// <param name="provider">The <see cref="INotificationMethodProvider"/>.</param>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task SentAsync(INotificationMethodProvider provider, NotificationContext context);
 
+    /// <summary>
+    /// Occurs when the notification is failed.
+    /// </summary>
+    /// <param name="provider">The <see cref="INotificationMethodProvider"/>.</param>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task FailedAsync(INotificationMethodProvider provider, NotificationContext context);
 
+    /// <summary>
+    /// Occurs before the notification is sent.
+    /// </summary>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task SendingAsync(NotificationContext context);
 
+    /// <summary>
+    /// Occurs after the notification is sent.
+    /// </summary>
+    /// <param name="context">The <see cref="NotificationContext"/>.</param>
     Task SentAsync(NotificationContext context);
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMessage.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMessage.cs
index 07274993589..c5e820a9d5e 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMessage.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMessage.cs
@@ -1,12 +1,27 @@
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a contract for notification message information.
+/// </summary>
 public interface INotificationMessage
 {
+    /// <summary>
+    /// Gets the message summary.
+    /// </summary>
     string Summary { get; }
 
+    /// <summary>
+    /// Gets the plain message body.
+    /// </summary>
     string TextBody { get; }
 
+    /// <summary>
+    /// Gets the HTML message body.
+    /// </summary>
     string HtmlBody { get; }
 
+    /// <summary>
+    /// Gets whether HTML is preferred for the message body.
+    /// </summary>
     bool IsHtmlPreferred { get; }
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProvider.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProvider.cs
index d2766cc2519..0daf2f24c10 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProvider.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProvider.cs
@@ -3,23 +3,27 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a contract for a notification provider.
+/// </summary>
 public interface INotificationMethodProvider
 {
     /// <summary>
-    /// Unique name for the provider.
+    /// Gets the provider name.
     /// </summary>
+    /// <remarks>The name should be unique.</remarks>
     string Method { get; }
 
     /// <summary>
-    /// A localized name for the method.
+    /// Gets a localized name for the method.
     /// </summary>
     LocalizedString Name { get; }
 
     /// <summary>
     /// Attempts to send the given message to the given notifiable object.
     /// </summary>
-    /// <param name="notify"></param>
-    /// <param name="message"></param>
+    /// <param name="notify">The notifiable object.</param>
+    /// <param name="message">The <see cref="INotificationMessage"/>.</param>
     /// <returns><c>true</c> when the message was successfully sent otherwise <c>false</c>.</returns>
     Task<bool> TrySendAsync(object notify, INotificationMessage message);
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProviderAccessor.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProviderAccessor.cs
index 0bab8e15ee9..3263320a444 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProviderAccessor.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationMethodProviderAccessor.cs
@@ -3,7 +3,15 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a contract for accessing the <see cref="INotificationMethodProvider"/>.
+/// </summary>
 public interface INotificationMethodProviderAccessor
 {
+    /// <summary>
+    /// Gets the registered notification method providers.
+    /// </summary>
+    /// <param name="notify">The notifiable object.</param>
+    /// <returns>A list of <see cref="INotificationMethodProvider"/>.</returns>
     Task<IEnumerable<INotificationMethodProvider>> GetProvidersAsync(object notify);
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationService.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationService.cs
index db416cc3252..ef123fe1607 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationService.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/INotificationService.cs
@@ -2,13 +2,16 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Contract for notification service.
+/// </summary>
 public interface INotificationService
 {
     /// <summary>
     /// Attempts to send the given message to the given notifiable object.
     /// </summary>
-    /// <param name="notify"></param>
-    /// <param name="message"></param>
+    /// <param name="notify">The notifiable object.</param>
+    /// <param name="message">The message to be sent.</param>
     /// <returns>The number of messages that were successfully sent to the user.</returns>
     Task<int> SendAsync(object notify, INotificationMessage message);
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/Notification.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/Notification.cs
index c366b5e4584..96efa051790 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/Notification.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/Notification.cs
@@ -3,25 +3,28 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a notification entity.
+/// </summary>
 public class Notification : Entity
 {
     /// <summary>
-    /// The Id of the notification.
+    /// Gets or sets the notification Id.
     /// </summary>
     public string NotificationId { get; set; }
 
     /// <summary>
-    /// The summary of the notification
+    /// Gets or sets the notification summary.
     /// </summary>
     public string Summary { get; set; }
 
     /// <summary>
-    /// The user id of the user who caused the event to occur.
+    /// Gets or sets the user id who caused the event to occur.
     /// </summary>
     public string UserId { get; set; }
 
     /// <summary>
-    /// The date and time when the event occurred.
+    /// Gets or sets the date and time when the event occurred.
     /// </summary>
     public DateTime CreatedUtc { get; set; }
 }
diff --git a/src/OrchardCore/OrchardCore.Notifications.Abstractions/NotificationContext.cs b/src/OrchardCore/OrchardCore.Notifications.Abstractions/NotificationContext.cs
index 13f0025465d..45cd53199e3 100644
--- a/src/OrchardCore/OrchardCore.Notifications.Abstractions/NotificationContext.cs
+++ b/src/OrchardCore/OrchardCore.Notifications.Abstractions/NotificationContext.cs
@@ -2,17 +2,35 @@
 
 namespace OrchardCore.Notifications;
 
+/// <summary>
+/// Represents a context for notification.
+/// </summary>
 public class NotificationContext
 {
-    public Notification Notification { get; set; }
-
-    public INotificationMessage NotificationMessage { get; }
-
-    public object Notify { get; }
-
+    /// <summary>
+    /// Creates a new instance of <see cref="NotificationContext"/>.
+    /// </summary>
+    /// <param name="notificationMessage">The notification message.</param>
+    /// <param name="notify">The notifiable object.</param>
+    /// <exception cref="ArgumentNullException">Occurs when <paramref name="notificationMessage"/> is <c>null</c>,</exception>
     public NotificationContext(INotificationMessage notificationMessage, object notify)
     {
         NotificationMessage = notificationMessage ?? throw new ArgumentNullException(nameof(notificationMessage));
         Notify = notify ?? throw new ArgumentNullException(nameof(notify));
     }
+
+    /// <summary>
+    /// Gets ot sets the notification.
+    /// </summary>
+    public Notification Notification { get; set; }
+
+    /// <summary>
+    /// Gets or sets the notification message.
+    /// </summary>
+    public INotificationMessage NotificationMessage { get; }
+
+    /// <summary>
+    /// Gets or sets the notifiable object.
+    /// </summary>
+    public object Notify { get; }
 }