Write legacy Proffer.Emails code documentation #10

src/Proffer.Email.InMemory/IInMemoryEmailRepository.cs

@@ -1,11 +1,21 @@
-namespace Proffer.Email.InMemory
+namespace Proffer.Email.InMemory
 {
     using System.Collections.Generic;
 
+    /// <summary>
+    /// A repository in memory to hold sent emails through the provider.
+    /// </summary>
     public interface IInMemoryEmailRepository
     {
+        /// <summary>
+        /// Gets the emails store.
+        /// </summary>
         IReadOnlyCollection<InMemoryEmail> Store { get;}
 
+        /// <summary>
+        /// Saves the specified email in the store.
+        /// </summary>
+        /// <param name="email">The email.</param>
         void Save(InMemoryEmail email);
     }
 }

src/Proffer.Email.InMemory/InMemoryEmail.cs

@@ -1,25 +1,55 @@
-using System.Collections.Generic;
-
 namespace Proffer.Email.InMemory
 {
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// An object to retain the values of the email that would have been sent.
+    /// </summary>
     public class InMemoryEmail
     {
+        /// <summary>
+        /// Gets or sets the subject.
+        /// </summary>
         public string Subject { get; set; }
 
+        /// <summary>
+        /// Gets or sets the message as plain-text.
+        /// </summary>
         public string MessageText { get; set; }
 
+        /// <summary>
+        /// Gets or sets the message as HTML.
+        /// </summary>
         public string MessageHtml { get; set; }
 
+        /// <summary>
+        /// Gets or sets the email recipients.
+        /// </summary>
         public IEmailAddress[] To { get; set; }
 
+        /// <summary>
+        /// Gets or sets the email recipients.
+        /// </summary>
         public IEmailAddress[] Cc { get; set; }
 
+        /// <summary>
+        /// Gets or sets the BCC email recipients.
+        /// </summary>
         public IEmailAddress[] Bcc { get; set; }
 
+        /// <summary>
+        /// Gets or sets the sender email address.
+        /// </summary>
         public IEmailAddress From { get; set; }
 
+        /// <summary>
+        /// Gets or sets the reply-to email address.
+        /// </summary>
         public IEmailAddress ReplyTo { get; set; }
 
+        /// <summary>
+        /// Gets or sets the attachments files.
+        /// </summary>
         public IEnumerable<IEmailAttachment> Attachments { get; set; }
     }
 }

src/Proffer.Email.InMemory/InMemoryEmailProvider.cs

@@ -1,35 +1,77 @@
-namespace Proffer.Email.InMemory
+namespace Proffer.Email.InMemory
 {
     using System.Collections.Generic;
     using System.Linq;
     using System.Threading.Tasks;
 
+    /// <summary>
+    /// A provider which does not send any email but holds it in a collection in memory.
+    /// </summary>
+    /// <seealso cref="IEmailProvider" />
     public class InMemoryEmailProvider : IEmailProvider
     {
         private readonly IInMemoryEmailRepository inMemoryEmailRepository;
 
-        public InMemoryEmailProvider(IEmailProviderOptions options, IInMemoryEmailRepository inMemoryEmailRepository)
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InMemoryEmailProvider"/> class.
+        /// </summary>
+        /// <param name="inMemoryEmailRepository">The in-memory email repository.</param>
+        public InMemoryEmailProvider(IInMemoryEmailRepository inMemoryEmailRepository)
         {
             this.inMemoryEmailRepository = inMemoryEmailRepository;
         }
 
-        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string text, string html)
-        {
-            return SendEmailAsync(from, recipients, subject, text, html, Enumerable.Empty<IEmailAttachment>());
-        }
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="recipients">The email recipients.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="bodyText">The body as plain text.</param>
+        /// <param name="bodyHtml">The body as HTML.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
+        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string bodyText, string bodyHtml)
+            => this.SendEmailAsync(from, recipients, subject, bodyText, bodyHtml, Enumerable.Empty<IEmailAttachment>());
 
-        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string text, string html, IEnumerable<IEmailAttachment> attachments)
-        {
-            return SendEmailAsync(from, recipients, Enumerable.Empty<IEmailAddress>(), Enumerable.Empty<IEmailAddress>(), subject, text, html, Enumerable.Empty<IEmailAttachment>());
-        }
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="recipients">The email recipients.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="bodyText">The body as plain text.</param>
+        /// <param name="bodyHtml">The body as HTML.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
+        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string bodyText, string bodyHtml, IEnumerable<IEmailAttachment> attachments)
+            => this.SendEmailAsync(from, recipients, Enumerable.Empty<IEmailAddress>(), Enumerable.Empty<IEmailAddress>(), subject, bodyText, bodyHtml, Enumerable.Empty<IEmailAttachment>());
 
-        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, IEnumerable<IEmailAddress> ccRecipients, IEnumerable<IEmailAddress> bccRecipients, string subject, string text, string html, IEnumerable<IEmailAttachment> attachments, IEmailAddress replyTo = null)
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="recipients">The email recipients.</param>
+        /// <param name="ccRecipients">The CC email recipients.</param>
+        /// <param name="bccRecipients">The BCC email recipients.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="bodyText">The body as plain text.</param>
+        /// <param name="bodyHtml">The body as HTML.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
+        public Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, IEnumerable<IEmailAddress> ccRecipients, IEnumerable<IEmailAddress> bccRecipients, string subject, string bodyText, string bodyHtml, IEnumerable<IEmailAttachment> attachments, IEmailAddress replyTo = null)
         {
             this.inMemoryEmailRepository.Save(new InMemoryEmail
             {
                 Subject = subject,
-                MessageText = text,
-                MessageHtml = html,
+                MessageText = bodyText,
+                MessageHtml = bodyHtml,
                 To = recipients.ToArray(),
                 Cc = ccRecipients.ToArray(),
                 Bcc = bccRecipients.ToArray(),

src/Proffer.Email.InMemory/InMemoryEmailProviderType.cs

@@ -1,19 +1,35 @@
-namespace Proffer.Email.InMemory
+namespace Proffer.Email.InMemory
 {
+    /// <summary>
+    /// Builds <see cref="InMemoryEmailProvider"/>.
+    /// </summary>
+    /// <seealso cref="IEmailProviderType" />
     public class InMemoryEmailProviderType : IEmailProviderType
     {
+        /// <summary>
+        /// Gets the name.
+        /// </summary>
         public string Name => "InMemory";
 
-        private IInMemoryEmailRepository inMemoryEmailRepository;
+        private readonly IInMemoryEmailRepository inMemoryEmailRepository;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InMemoryEmailProviderType"/> class.
+        /// </summary>
+        /// <param name="inMemoryEmailRepository">The in-memory email repository.</param>
         public InMemoryEmailProviderType(IInMemoryEmailRepository inMemoryEmailRepository)
         {
             this.inMemoryEmailRepository = inMemoryEmailRepository;
         }
 
-        public IEmailProvider BuildProvider(IEmailProviderOptions options)
-        {
-            return new InMemoryEmailProvider(options, this.inMemoryEmailRepository);
-        }
+        /// <summary>
+        /// Builds the provider.
+        /// </summary>
+        /// <param name="providerOptions">The provider options.</param>
+        /// <returns>
+        /// A new <see cref="IEmailProvider" />.
+        /// </returns>
+        public IEmailProvider BuildProvider(IEmailProviderOptions providerOptions)
+            => new InMemoryEmailProvider(this.inMemoryEmailRepository);
     }
 }

src/Proffer.Email.InMemory/InMemoryEmailRepository.cs

@@ -1,23 +1,25 @@
-namespace Proffer.Email.InMemory
+namespace Proffer.Email.InMemory
 {
     using System.Collections.Generic;
     using System.Collections.ObjectModel;
 
+    /// <summary>
+    /// A repository in memory to hold sent emails through the provider.
+    /// </summary>
+    /// <seealso cref="IInMemoryEmailRepository" />
     public class InMemoryEmailRepository : IInMemoryEmailRepository
     {
-        private List<InMemoryEmail> innerEmailStore = new List<InMemoryEmail>();
+        private readonly List<InMemoryEmail> innerEmailStore = new();
 
-        public IReadOnlyCollection<InMemoryEmail> Store
-        {
-            get
-            {
-                return new ReadOnlyCollection<InMemoryEmail>(innerEmailStore);
-            }
-        }
+        /// <summary>
+        /// Gets the emails store.
+        /// </summary>
+        public IReadOnlyCollection<InMemoryEmail> Store => new ReadOnlyCollection<InMemoryEmail>(this.innerEmailStore);
 
-        public void Save(InMemoryEmail email)
-        {            
-            this.innerEmailStore.Add(email);
-        }
+        /// <summary>
+        /// Saves the specified email in the store.
+        /// </summary>
+        /// <param name="email">The email.</param>
+        public void Save(InMemoryEmail email) => this.innerEmailStore.Add(email);
     }
 }

src/Proffer.Email.InMemory/ServiceCollectionExtensions.cs

@@ -1,11 +1,19 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
     using InMemory;
     using Microsoft.Extensions.DependencyInjection;
     using Microsoft.Extensions.DependencyInjection.Extensions;
 
+    /// <summary>
+    /// <see cref="IServiceCollection"/> extension methods.
+    /// </summary>
     public static class ServiceCollectionExtensions
     {
+        /// <summary>
+        /// Registers the Proffer.Email services to an in-memory collection.
+        /// </summary>
+        /// <param name="services">The service collection.</param>
+        /// <returns>The service collection.</returns>
         public static IServiceCollection AddInMemoryEmail(this IServiceCollection services)
         {
             services.TryAddEnumerable(ServiceDescriptor.Transient<IEmailProviderType, InMemoryEmailProviderType>());

src/Proffer.Email.SendGrid/EmailAddressExtensions.cs

@@ -0,0 +1,20 @@
+namespace Proffer.Email.SendGrid
+{
+    using global::SendGrid.Helpers.Mail;
+
+    /// <summary>
+    /// <see cref="IEmailAddress"/> extension methods.
+    /// </summary>
+    internal static class EmailAddressExtensions
+    {
+        /// <summary>
+        /// Converts an email address to its equivalent SendGrid model.
+        /// </summary>
+        /// <param name="email">The email.</param>
+        /// <returns>The SendGrid model for the email address.</returns>
+        internal static EmailAddress ToSendGridEmail(this IEmailAddress email)
+        {
+            return new EmailAddress(email.Email, email.DisplayName);
+        }
+    }
+}