Proffer.Email code documentation done #10

src/Proffer.Email/EmailTemplateType.cs

@@ -1,9 +1,23 @@
 namespace Proffer.Email
 {
+    /// <summary>
+    /// Type of template for a templated email.
+    /// </summary>
     public enum EmailTemplateType
     {
+        /// <summary>
+        /// The templated subject.
+        /// </summary>
         Subject,
+
+        /// <summary>
+        /// The templated body as HTML.
+        /// </summary>
         BodyHtml,
+
+        /// <summary>
+        /// The templated body as plain-text.
+        /// </summary>
         BodyText
     }
 }

src/Proffer.Email/IEmailAddress.cs

@@ -1,9 +1,18 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
+    /// <summary>
+    /// An email address with its optional display name.
+    /// </summary>
     public interface IEmailAddress
     {
+        /// <summary>
+        /// Gets the email.
+        /// </summary>
         string Email { get; }
 
+        /// <summary>
+        /// Gets the display name.
+        /// </summary>
         string DisplayName { get; }
     }
 }

src/Proffer.Email/IEmailAttachment.cs

@@ -1,11 +1,33 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
+    /// <summary>
+    /// An email attachment file.
+    /// </summary>
     public interface IEmailAttachment
     {
+        /// <summary>
+        /// Gets or sets the file name.
+        /// </summary>
         string FileName { get; set; }
+
+        /// <summary>
+        /// Gets or sets the file content.
+        /// </summary>
         byte[] Data { get; set; }
+
+        /// <summary>
+        /// Gets or sets the media type.
+        /// </summary>
         string MediaType { get; set; }
+
+        /// <summary>
+        /// Gets or sets the media subtype.
+        /// </summary>
         string MediaSubtype { get; set; }
+
+        /// <summary>
+        /// Gets the content-type.
+        /// </summary>
         string ContentType { get; }
     }
 }

src/Proffer.Email/IEmailProvider.cs

@@ -1,14 +1,55 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
     using System.Collections.Generic;
     using System.Threading.Tasks;
 
+    /// <summary>
+    /// A provider sends email using a particular messaging protocol or API.
+    /// </summary>
     public interface IEmailProvider
     {
+        /// <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>
         Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string bodyText, string bodyHtml);
 
+        /// <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>
         Task SendEmailAsync(IEmailAddress from, IEnumerable<IEmailAddress> recipients, string subject, string bodyText, string bodyHtml, IEnumerable<IEmailAttachment> attachments);
 
+        /// <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>
         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);
     }
 }

src/Proffer.Email/IEmailProviderType.cs

@@ -1,9 +1,20 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
+    /// <summary>
+    /// Builds providers using a particular messaging protocol or API.
+    /// </summary>
     public interface IEmailProviderType
     {
+        /// <summary>
+        /// Gets the name.
+        /// </summary>
         string Name { get; }
 
+        /// <summary>
+        /// Builds the provider.
+        /// </summary>
+        /// <param name="providerOptions">The provider options.</param>
+        /// <returns>A new <see cref="IEmailProvider"/>.</returns>
         IEmailProvider BuildProvider(IEmailProviderOptions providerOptions);
     }
 }

src/Proffer.Email/IEmailSender.cs

@@ -1,32 +1,178 @@
-namespace Proffer.Email
+namespace Proffer.Email
 {
     using System.Collections.Generic;
     using System.Threading.Tasks;
 
+    /// <summary>
+    /// Sends templated or raw emails using configured providers.
+    /// </summary>
     public interface IEmailSender
     {
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(string subject, string message, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(IEmailAddress from, string subject, string message, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="plainTextOnly">If set to <c>true</c> the body shoud be sent as plain text only.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(IEmailAddress from, IEmailAddress replyTo, string subject, string message, bool plainTextOnly, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(IEmailAddress from, string subject, string message, IEnumerable<IEmailAttachment> attachments, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="plainTextOnly">If set to <c>true</c> the body shoud be sent as plain text only.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(IEmailAddress from, IEmailAddress replyTo, string subject, string message, bool plainTextOnly, IEnumerable<IEmailAttachment> attachments, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends an email.
+        /// </summary>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="subject">The subject.</param>
+        /// <param name="message">The body as plain text.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <param name="cc">The CC email recipients.</param>
+        /// <param name="bcc">The BCC email recipients.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <param name="plainTextOnly">If set to <c>true</c> the body shoud be sent as plain text only.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendEmailAsync(IEmailAddress from, string subject, string message, IEnumerable<IEmailAttachment> attachments, IEmailAddress[] to, IEmailAddress[] cc, IEmailAddress[] bcc, IEmailAddress replyTo = null, bool plainTextOnly = false);
 
+        /// <summary>
+        /// Sends a templated email from the configured default sender email address.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(string templateKey, T context, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends a templated email.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(IEmailAddress from, string templateKey, T context, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends a templated email.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(IEmailAddress from, IEmailAddress replyTo, string templateKey, T context, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends a templated email.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(IEmailAddress from, string templateKey, T context, IEnumerable<IEmailAttachment> attachments, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends a templated email.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(IEmailAddress from, IEmailAddress replyTo, string templateKey, T context, IEnumerable<IEmailAttachment> attachments, params IEmailAddress[] to);
 
+        /// <summary>
+        /// Sends a templated email.
+        /// </summary>
+        /// <typeparam name="T">The type of context to apply on the template.</typeparam>
+        /// <param name="from">The sender email address.</param>
+        /// <param name="templateKey">The template key.</param>
+        /// <param name="context">The context  to apply on the template.</param>
+        /// <param name="attachments">The file attachments.</param>
+        /// <param name="to">The email recipients.</param>
+        /// <param name="cc">The CC email recipients.</param>
+        /// <param name="bcc">The BCC email recipients.</param>
+        /// <param name="replyTo">The reply-to email address.</param>
+        /// <returns>
+        /// A task that represents the asynchronous operation.
+        /// </returns>
         Task SendTemplatedEmailAsync<T>(IEmailAddress from, string templateKey, T context, IEnumerable<IEmailAttachment> attachments, IEmailAddress[] to, IEmailAddress[] cc, IEmailAddress[] bcc, IEmailAddress replyTo = null);
     }
 }

src/Proffer.Email/Internal/EmailAddress.cs

@@ -1,19 +1,37 @@
 namespace Proffer.Email.Internal
 {
+    /// <summary>
+    /// A simple email address with its optional display name.
+    /// </summary>
+    /// <seealso cref="IEmailAddress" />
     public class EmailAddress : IEmailAddress
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EmailAddress"/> class.
+        /// </summary>
         public EmailAddress()
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EmailAddress"/> class.
+        /// </summary>
+        /// <param name="email">The email.</param>
+        /// <param name="displayName">The display name.</param>
         public EmailAddress(string email, string displayName)
         {
             this.Email = email;
             this.DisplayName = displayName;
         }
 
+        /// <summary>
+        /// Gets or sets the email.
+        /// </summary>
         public string Email { get; set; }
 
+        /// <summary>
+        /// Gets or sets the display name.
+        /// </summary>
         public string DisplayName { get; set; }
     }
 }