Added comments to interfaces.

Author: danzuep

source/MailKitSimplified.Receiver/Abstractions/IImapReceiver.cs

@@ -9,16 +9,47 @@ namespace MailKitSimplified.Receiver.Abstractions
 {
     public interface IImapReceiver : IAsyncDisposable, IDisposable
     {
+        /// <summary>
+        /// Read emails fluently from the default mail folder.
+        /// </summary>
         IMailReader ReadMail { get; }
 
+        /// <summary>
+        /// Connect to a mail folder and read emails fluently.
+        /// </summary>
+        /// <param name="mailFolderName">Mail folder to read from.</param>
+        /// <returns><see cref="IMailReader"/>.</returns>
         IMailReader ReadFrom(string mailFolderName);
 
+        /// <summary>
+        /// Get a list of the names of all the folders connected to this account.
+        /// </summary>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>Names of all connected mail folders.</returns>
         ValueTask<IList<string>> GetMailFolderNamesAsync(CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Connect and authenticate the IMAP client.
+        /// </summary>
+        /// <param name="cancellationToken">Stop connecting the client.</param>
+        /// <returns>Connected <see cref="IImapClient">IMAP client</see>.</returns>
         ValueTask<IImapClient> ConnectImapClientAsync(CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Connect to the given mail folder.
+        /// </summary>
+        /// <param name="mailFolderName">Mail folder name.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>Connected <see cref="IMailFolder"/>.</returns>
         ValueTask<IMailFolder> ConnectMailFolderAsync(string mailFolderName = null, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Connect an <see cref="IMailFolderClient"/> to the mail folder.
+        /// </summary>
+        /// <param name="mailFolderName">Mail folder name.</param>
+        /// <param name="enableWrite">Optionally enable ReadWrite access.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns><see cref="IMailFolderClient"/>.</returns>
         ValueTask<IMailFolderClient> ConnectMailFolderClientAsync(string mailFolderName = null, bool enableWrite = false, CancellationToken cancellationToken = default);
     }
 }

source/MailKitSimplified.Receiver/Abstractions/IMailFolderClient.cs

@@ -7,8 +7,14 @@ namespace MailKitSimplified.Receiver.Abstractions
 {
     public interface IMailFolderClient : IAsyncDisposable, IDisposable
     {
+        /// <summary>Connect to the configured mail folder.</summary>
+        /// <param name="enableWrite">Optionally enable ReadWrite access.</param>
+        /// <param name="cancellationToken">Mail folder connection cancellation token.</param>
+        /// <returns>Connected <see cref="IMailFolder"/>.</returns>
         ValueTask<IMailFolder> ConnectAsync(bool enableWrite = false, CancellationToken cancellationToken = default);
 
+        /// <summary>Mail folder summary.</summary>
+        /// <returns>Mail folder name and count.</returns>
         string ToString();
     }
 }

source/MailKitSimplified.Receiver/Abstractions/IMailFolderReader.cs

@@ -9,12 +9,37 @@ namespace MailKitSimplified.Receiver.Abstractions
 {
     public interface IMailFolderReader : IAsyncDisposable, IDisposable
     {
+        /// <summary>
+        /// Connect or reconnect to the given mail folder.
+        /// </summary>
+        /// <param name="enableWrite">Optionally enable ReadWrite access.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>Connected <see cref="IMailFolder"/>.</returns>
         ValueTask<IMailFolder> ReconnectAsync(bool enableWrite = false, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Get message summaries with just the requested items filled in for the specified unique IDs.
+        /// </summary>
+        /// <param name="uniqueIds">Messages to download by <see cref="UniqueId">ID</see>.</param>
+        /// <param name="filter"><see cref="MessageSummaryItems"/> to download.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>Collection of <see cref="IMessageSummary"/> items.</returns>
         ValueTask<IEnumerable<IMessageSummary>> GetMessageSummariesAsync(IEnumerable<UniqueId> uniqueIds, MessageSummaryItems filter = MessageSummaryItems.UniqueId, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Get a <see cref="MimeMessage"/> by unique ID.
+        /// </summary>
+        /// <param name="uniqueId">Message to download by <see cref="UniqueId">ID</see>.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>List of <see cref="IMessageSummary"/> items.</returns>
         ValueTask<MimeMessage> GetMimeMessageAsync(UniqueId uniqueId, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Get <see cref="MimeMessage"/>s by their unique IDs.
+        /// </summary>
+        /// <param name="uniqueIds">Messages to download by <see cref="UniqueId">ID</see>.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>List of <see cref="MimeMessage"/> items.</returns>
         ValueTask<IList<MimeMessage>> GetMimeMessagesAsync(IEnumerable<UniqueId> uniqueIds, CancellationToken cancellationToken = default);
     }
 }

source/MailKitSimplified.Receiver/Abstractions/IMailReader.cs

@@ -8,14 +8,42 @@ namespace MailKitSimplified.Receiver.Abstractions
 {
     public interface IMailReader
     {
+        /// <summary>
+        /// Offset to start getting messages from.
+        /// </summary>
+        /// <param name="skipCount">Offset to start getting messages from.</param>
+        /// <param name="continuous">Whether to keep adding the offset or not.</param>
+        /// <returns>Fluent <see cref="IMailReader"/>.</returns>
         IMailReader Skip(int skipCount, bool continuous = false);
 
+        /// <summary>
+        /// Number of messages to return.
+        /// </summary>
+        /// <param name="takeCount">Number of messages to return.</param>
+        /// <returns>Fluent <see cref="IMailReader"/>.</returns>
         IMailReader Take(int takeCount);
 
+        /// <summary>
+        /// Get a list of the message summaries with just the requested MessageSummaryItems.
+        /// </summary>
+        /// <param name="filter"><see cref="MessageSummaryItems"/> to download.</param>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>List of <see cref="IMessageSummary"/> items.</returns>
         ValueTask<IList<IMessageSummary>> GetMessageSummariesAsync(MessageSummaryItems filter, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Get a list of the message summaries with basic MessageSummaryItems.
+        /// </summary>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <returns>List of <see cref="IMessageSummary"/> items.</returns>
         ValueTask<IList<IMessageSummary>> GetMessageSummariesAsync(CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Get a list of <see cref="MimeMessage"/>s.
+        /// </summary>
+        /// <param name="cancellationToken">Request cancellation token.</param>
+        /// <param name="transferProgress">Current email download progress</param>
+        /// <returns>List of all <see cref="MimeMessage"/> items.</returns>
         ValueTask<IList<MimeMessage>> GetMimeMessagesAsync(CancellationToken cancellationToken = default, ITransferProgress transferProgress = null);
     }
 }